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Preface 



This publication consists of self-contained 
chapters, each of which provides system 
programmers with information on how to 
modify, extend, or implement the data 
management capabilities of the IBM 
System/360 Operating System control 
program. Although the information in one 
chapter is sometimes related to information 
in another, all chapters have been written 
as separate and complete units. It is 
assumed that users of this publication are 
thoroughly familiar with the design of the 
operating system and its features. Such 
information can be obtained in IBM 
System/360 Operating System: Introduction , 
GC28-6534. Each chapter contains its own 
introductory section and list of 
prerequisite publications. This 
organization has been used to reduce 
cross-referencing and to facilitate the 
addition of new chapters. 
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Summary of Amendments 

for GC28-6550-10 

OS Release 21 



NEW DEVICE SUPPORT 

Information is added to support the IBM 
3803/3420 Magnetic Tape Subsystem and 
the IBM 3505/352 5 Card Reader/Card 
Punch. 



CATALOG MANAGEMENT 

Changes have been made to the section 
on catalog and VTOC maintenance to show 
changes in the method of adding, 
deleting and naming data sets in the 
catalog. 



MACRO INSTRUCTIONS ADDED 

Information is added about the CVT and 
LABEL macro instructions. 



ORGANIZATION CHANGE 

Information from the following chapters 
has been relocated to the IBM 
System/360 Operating System MFT Guide , 
GC27-6939: 

The Must Complete Function 

Job Queue Formatting 

The PRESRES Volume Characteristics 

List 
Output Separation 

Writing System Output Writer Routines 
Adding SVC Routines to the Control 

Program 
Message Routing Exit Routines 
Handling Accounting Routines 
Reader/Interpreter and Output Writer 

Cataloged Procedures 
Resident Routines Option 
The Shared DASD Option 
The Time Slicing Facility 
System Macro Instructions (except 

DEVTYPE, OPEN, and RDJFCB) 

Information from the following chapters 
has been relocated to the IBM 
System/360 Operating System MVT Guide , 
GC28-6720: 



The Must Complete Function 

Job Queue Formatting 

The PRESRES Volume Characteristics 

List 
Output Separation 

Writing System Output Writer Routines 
Adding SVC Routines to the Control 

Program 
Message Routing Exit Routines 
Handling Accounting Routines 
Reader/Interpreter and Output Writer 

Cataloged Procedures - Dedicated 

Data Sets 
Using the Link Pack Area 
Writing Rollout/Rollin Installation 

Appendages 
The Shared DASD Option 
The Time Slicing Facility 
System Macro Instructions (except 

DEVTYPE, OPEN, and RDJFCB) 

The chapter about graphic job 
processing has been relocated to the 
User's Guide for Job Control from the 
IBM 2250 Display Unit , GC27-6933. 

The chapter about satellite graphic job 
processing has been relocated to the 
User's Guide for Job Control from the 
IBM 2250 Display Unit Attached to an 
IBM 1130 System , GC27-6938. 

The chapter about System Management 
Facilities was removed during the last 
revision. The information may now be 
found in IBM System/360 Operating 
System SMF Guide , GC28-6715. 

Information about the tracing routine 
option may now be found in IBM System/36 
Operating System; Programmer' r s' Guide to 
Debugging , GC28-6670. 

MISCELLANEOUS CHANGES 

Information is added to clarify 
specifications of the password data set 
and the use of the IEHPROGM utility 
program for updating the password data 
set. 

New Event Control Block (ECB) codes 
have been added to the descriptions in 
the EXCP and XDAP macro instruction 
sections. 
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Summary of Amendments 
for GC28-6550-9 
OS Release 20.1 



r 

| Item 



TSO 



| Description 



The PURGE parameter list has a 
fourth word that can be used to 
purge a list of TCBs. 



| Chapter Affected 

+ 

Execute Channel Proqram 



START command 



The START command can now be used 
to start a problem program. 



-+ 



System Reader, Initiator, 
and Writer Cataloged 
procedures 



709 4 Emulator 



Change to the ASB procedure for 
7094 Emulator 



System Reader, Initiator, 
and Writer Cataloged 
Procedures 



FORTRAN G 



Change to data blocking for 
FORTRAN G 



System Reader, Initiator, 
and Writer Cataloged 
Procedures 



STAE 



Change to STAE retry routine 
procedure 



System Macro Instructions 



PROTECT 



Additional return code for 
PROTECT macro instruction 



Data Set Protection 



3211 Printer 



New device dependent information 
for the 3211 Printer 



IECDSECT, IEFJFCBN, and 
IEFUCBOB Macro Instructions 

Execute Direct Access 
Program (XDAP) Macro 
Instructions 

System Macro Instructions 

Writing System Output Writer 
Routines 

Output Separation 

System Reader, Initiator, 
and Writer Cataloged 
procedures 

Adding a Universal Character 
Set Image or FCB Image to 
the Image Library 



3330 and 2305 
Direct Access 
Devices 



New device dependent information 
for the 3330 and 2305 Direct 
Access Devices 



Maintaining the Catalog 
and the Volume Table of 
Contents 

Execute Direct Access 
Program (XDAP) Macro 
Instruction 

System Macro Instructions 

The Shared Direct Access 
Storage Device Option 
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Summary of Amendments 

for GC28-6550-8 

as Updated by GN28-2452 

OS Release 20 



"T T 

| Chapter Affected | 



Item 



| Description 



PROTECT Macro 
Instruction 



A new macro instruction that can be used to 
maintain the password data set has been added. 



Data Set 
Protection. 



STAE Macro 
Instruction 



Two new parameters have been added. 



System Macro 
Instructions . 



-+- 



ASCII 



The macro definitions for the UCB and JFCB 
have been modified to include ASCII. In 
addition, restrictions against using ASCII 
data sets in the reader input stream have been 
added. 



IECDSECT, IEFJFCBN, 
and IEFUCBOB Macro 
Instruct ions . 

System Reader, 
Initiator, and 
Writer Cataloged 
Procedures . 



Models 155/165 



New devices have been added to the device type 
characteristics description. 



System Macro 
Instructions . 



Dedicated Data Sets 



Additional information on the disposition 
of dedicated data sets, by 
allocation/termination, has been added. 



System Reader, 
Initiator, and 
Writer Cataloged 
Procedures. 



Direct System 
Output Writer 



The description of the direct system output 
writer procedure has been changed to omit the 
separator function. 



System Reader, 
Initiator, and 
Writer Cataloged 
Procedures . 



-+- 



2150 Console 



The 2150 console has been removed from the 
device type characteristics description. 



System Macro 
Instructions . 



SYS1.MANX and 
SYS1.MANY 



Addition of SYSl.MANX and SYSl.MANY to list 
of data sets that cannot be shared. 



-+- 



The Shared 
Di rect-Access 
Device Option. 



GSP Routines 



Addition of reenterable GSP routines to group 
of modules that can be put in the MFT link 
pack area. 



Resident Routines 
Option. 



System Management 
Facilities 



Modifications to the MDL= and OPI= 
parameters. 



System Management 
Facilities. 



Procedure INITD 



Removal of ABEND DD statement from INITD 
procedure. 



System Reader, 
Initiator, and 
Writer Routines. 
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CONTENTS DIRECTORY 



Maintaining the Catalog and the Volume Table of Contents 



IECDSECT, IEFJFCBN, and IEFUCBOB Macro Instructions 



Execute Channel Program (EXCP) Macro Instruction 



Execute Direct Access Program (XDAP) Macro Instruction 



Data Set Protection 



System Macro Instructions 



Adding a Universal Character Set Image or a Forms 
Control Buffer Image to the System Library 



Index 
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Maintaining the Catalog and 
the Volume Table of Contents 



This chapter provides detailed information 
on how to maintain and modify the catalog 
and volume table of contents. 

Before reading this chapter, you should 
be familiar with the information contained 
in the prerequisite publications listed 
below. 



PREREQUISITE PUBLICATIONS 

The IBM System/360 Operating System; 
Assembler Language publication (GC28-6514) 
contains the information necessary to code 
programs in the assembler language. 

The IBM System/360 Operating System: 
Data Management Services publication 
(GC26-3746) contains a general description 
of the structure of catalog indexes, as 
well as a brief discussion of the volume 
table of contents (VTOC) . 



COMPANION PUBLICATION 

The IBM System/360 Operating System: 
System Control Blocks publication 
(GC28-6628) contains format and field 
descriptions of the system control blocks 
referred to in this chapter. 



RECOMMENDED PUBLICATIONS 

The IBM System/360 Operating System: 
Utilities publication (GC28-6586) describes 
how to maintain and modify the catalog and 
the volume table of contents through the 
use of utility programs. 
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Maintaining the Catalog and the Volume Table of Contents 

This chapter describes how to maintain and modify the catalog and the 
volume table of contents through the use of macro instructions. Most of 
the maintenance and modification functions can also be performed using 
utility statements. The utility statements are described in the 
publication IBM System/360 Operating System: Utilities . 

The functions you can perform using the macro instructions are 
described in text, and the formats of the macro instructions are 
| tabulated on a fold- out sheet (Figure CTLG1) at the back of this book. 
The chart on the fold-out sheet associates the function described in 
text with the macro instructions needed to perform the function. You 
should keep the fold-out sheet open when reading the text. 

The functions that are described in text are: 

• How to read a block from the catalog. 

• How to build an index. 

• How to build a generation index. 

• How to delete an index. 

• How to assign an alias. 

• How to delete an alias. 

• How to connect control volumes. 

• How to disconnect control volumes. 

• How to catalog a data set. 

• How to remove data set references from the catalog. 

• How to recatalog a data set. 

• How to read a data set control block from the volume table of 
contents . 

• How to delete a data set. 

• How to rename a data set. 

Accompanying the function descriptions in text are coding examples 
and programming notes; exceptional -return condition codes for the macro 
instructions are tabulated on the back of the fold-out sheet (Figure 
CTLG2) . In the functional descriptions, bytes of data blocks are 
numbered from zero (the first byte is byte zero). 



HOW TO READ A BLOCK FROM THE CATALOG 

To read either an index block or a block indicating the volumes on which 
a data set is stored (volume-list block) , you use the LOCATE and CAMLST 
macro instructions. There are two ways to specify the block that you 
want read into main storage: by using the name of the index level or 
data set, or by using the block's location relative to the beginning of 
the catalog (TTR). 



I ~By Specifying the Name of a Data Set 



If you specify an index level name, the first block of the named index 
is read into main storage, and an exceptional return code is set. Index 
block formats are contained in Appendix A of this chapter. 

If you specify a data set name, a 256-byte volume- list block is read 
into main storage. The block contains up to 20 volume pointers, each of 
which points to a volume on which part of the data set is stored. The 
first two bytes of the block contain the number of volume pointers for 
the data set. Each volume pointer is a 12-byte field that contains a 
4-byte device code, a 6-byte volume serial number, and a 2-byte data set 
sequence number. (Device codes are contained in Appendix B of this 
chapter. ) 
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If the named data set is stored on more than 20 volumes, bytes 
252-254 of the block contain the relative track address of the next 
volume-list block of volume pointers. Byte 255 contains a binary zero. 

If the named data set is stored on only one volume, bytes 252-254 of 
the block contain the relative track address of the DSCB for that data 
set,, otherwise these bytes are zero. Byte 255 contains a binary zero. 

Example : In the following example, the list of volumes that contain 
data set A.B is read into main storage. The search for the volume-list 
block starts on the system residence volume. 




"T r 

j Operation | Operand 



Name 



•J 







1 LOCATE 


1 INDAB 




Check Exceptional Returns 




INDAB 


| CAMLST 


| NAME,AB,, LOCAREA 




AB 


| DC 


| CL44'A.B* 




LOCAREA 


| DS 


j 0D 






| DS 


| 265C 


1 




~L 


. J. 



READ VOLUME-LIST BLOCK FOR 
CATALOGED DATA SET A.B INTO 
MAIN STORAGE AREA NAMED 
LOCAREA. LOCAREA ALSO 
CONTAINS 3-BYTE TTR AND 
6-BYTE SERIAL NUMBER 



The LOCATE macro instruction points to the CAMLST macro instruction. 
NAME, the first operand of CAMLST, specifies that the system is to 
search the catalog for a volume-list block by using the name of a data 
set. AB, the second operand, specifies the main storage location of a 
44-byte area into which you have placed the fully qualified name of a 
data set. LOCAREA, the fourth operand, specifies a 265-byte area you 
have reserved in main storage. 

After execution of these macro instructions, the 265-byte area 
contains: the 256-byte volume-list block for the data set A.B and the 
6-byte serial number of the volume on which the block was found (in 
bytes 259-264). If data set A.B resides on only one volume, bytes 
252-254 of the volume-list block contain the relative track address of 
the DSCB for data set A.B (relative to the beginning of the VTOC) . 

If a code of 4 is returned in register 15 indicating that the 
| required control volume was not mounted, bytes 259-264 of the work area 

will contain the volume serial number of this required volume. If 

LOCATE finds an old CVOL pointer entry, and the CVOL is not mounted, 
| binary zeros will be returned in bytes 252-255 of the work area. 

However, if a new CVOL pointer entry is found, the four-byte device code 

of the CVOL will be returned in those bytes. 



-By Specifying the Name of a Generation Data Set 

You specify the name of a generation data set by using the fully 
qualified generation index name and the relative generation number of 
the data set. The value of a relative generation number reflects the 
position of a data set in a generation data group. The following values 
can be used: 

• Zero - specifies the latest data set cataloged in a generation data 
group. 

• Negative number - specifies a data set cataloged before the latest 
data set. 

• Positive number - specifies a data set not yet cataloged in the 
generation data group. 
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When you use zero or a negative number as the relative generation 
number, a volume-list block is read into main storage and the relative 
generation number is replaced by the absolute generation name. 

When you use a positive number as the relative generation number, an 
absolute generation name is created and replaces the relative generation 
number, A volume-list block is not read, since none exists for these 
data sets. 

Example ; In the following example, the list of volumes that contain 
generation data set A. PAY (-3) is read into main storage. The search for 
the volume-list block starts on the system residence volume. 

r t t 1 

| Name | Operation | Operand | 

j. + + j 

| LOCATE J INDGX READ VOLUME- LIST BLOCK FOR 

Check Exceptional Returns DATA SET A. PAY (-3) INTO 

INDGX | CAMLST | NAME,APAY, ,LOCAREA MAIN STORAGE AREA NAMED 

APAY j DC j CL44'A,PAY(-3) • LOCAREA. LOCAREA ALSO CON- 

LOCAREA | DS j OD TAINS 3-BYTE TTR AND 

| DS j 26 5C 6-BYTE SERIAL NUMBER 

L J. ._J J 

The LOCATE macro instruction points to the CAMLST macro instruction. 
NAME, the first operand of CAMLST, specifies that the system is to 
search the catalog for a volume-list block by using the name of a data 
set. APAY, the second operand, specifies the main storage location of a 
44-byte area into which you have placed the name of the generation index 
and the relative generation number of a data set in the generation data 
group. LOCAREA, the fourth operand, specifies a 265-byte area you have 
reserved in main storage. 

After execution of these macro instructions, the 265-byte area 
contains: the 256-byte volume-list block for generation data set 
A. PAY (-3) and the 6-byte serial number of the volume on which the block 
was found (in bytes 259-264). If data set A. PAY (-3) resides on one 
volume, bytes 252-254 of the volume-list block contain the relative 
track address of the DSCB for that data set (relative to the beginning 
of the VTOC) . In addition, the system will have replaced the relative 
generation number that you specified in your 44-byte area with the data 
set's absolute generation name. 

-By Specifying a Name Using an Alias 

For each of the preceding functions, you can specify an alias as the 
first name in the qualified name of an index level, data set, or 
generation data set. Each function is performed exactly as previously 
described, with one exception: the alias name specified is replaced by 
the true name. 

-By Specifying by TTR 

You can read any block in the catalog by specifying, in the form TTR, 
the identification of the block and its location relative to the 
beginning of the catalog. TT is the number of tracks from the beginning 
of the catalog, R is the record number of the desired block on the 
track. (Formats of each type of catalog block are contained in Appendix 
A of this chapter. ) 

Example : In the following example, the block at the location indicated 
by TTR is read into main storage. The specified block is in the catalog 
on the system residence volume. 
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I Name 
j. 



- T ,. 

| Operation | Operand 









1 


LOCATE 


1 


BLK 










Check Excepti 


onal Returns 






BLK 




1 


CAMLST 


1 


BLOCK 


r TTR, 


, LOCAREA 




TTR 




1 
1 


DC 
DC 


1 
1 


H'5' 
X'03* 








LOCAREA 


1 


DS 


1 


OD 












1 


DS 


1 


265C 

























READ A BLOCK INTO MAIN 
STORAGE AREA NAMED LOCAREA 

RELATIVE TRACK 5 

BLOCK 3 ON TRACK 

LOCAREA ALSO CONTAINS 3 -BYTE 

TTR AND 6 -BYTE SERIAL NO. 




The LOCATE macro instruction points to the CAMLST macro instruction. 
BLOCK, the first operand of CAMLST, specifies that the system is to 
search the catalog for the block indicated by TTR, the second operand. 
LOCAREA, the fourth operand, specifies a 265-byte area you have reserved 
in main storage. 

After execution of these macro instructions, the 265-byte area 
contains the 256-byte index block and the 6-byte serial number of the 
volume on which the block was found (in bytes 259-264). 

HOW TO BUILD AN INDEX 

To build a new index structure and add it to the catalog, you must 
create each level of the index separately. (You can also create index 
levels while you are cataloging a data set onto those index levels. See 
"How to Catalog a Data Set" in this chapter for details.) You create 
each level of the index by using the INDEX and CAMLST macro 
instructions . 

These two macro instructions can also be used to add index levels to 
existing index structures. 

Example ; In the following example, index structure A.B.C is built on 
the control volume whose serial number is 000045. 



■t r 

| Operation) Operand 



Name 



+ + 

J INDEX | INDEXA 
Check Exceptional Returns 

| INDEX | INDEXB 
Check Exceptional Returns 

| INDEX j INDEXC 
Check Exceptional Returns 
INDEXA | CAMLST | BLDX, ALEVEL,VOLNUM 
INDEXB | CAMLST | BLDX,BLEVEL,VOLNUM 
INDEXC | CAMLST j BLDX,CLEVEL,VOLNUM 
VOLNUM j DC | CL6* 000045* 
ALEVEL j DC | CL2 , A' 
BLEVEL | DC | CL4 , A.B f 
CLEVEL I DC I CLe'A.B.C* 



■I 



BUILD INDEX A 

BUILD INDEX STRUCTURE A. B 

BUILD INDEX STRUCTURE A.B.C 



VOLUME SERIAL NUMBER 
INDEX STRUCTURE NAMES 
FOLLOWED BY BLANKS 
WHICH DELIMIT FIELDS 



Each INDEX macro instruction points to an associated CAMLST macro 
instruction. BLDX, the first operand of CAMLST, specifies that an index 
level be built. The second operand specifies the main storage location 
of an area into which you have placed the fully qualified name of an 
index level. The third operand specifies the main storage location of 
an area into which you have placed the 6-byte serial number of the 
volume on which the index level is to be built. 
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HOW TO BUILD A GENERATION INDEX 

You build a generation index by using the INDEX and CAMLST macro 
instructions. All higher levels of the index roust exist. If the higher 
levels of the index are not in the catalog, you must build them. How to 
build an index has been explained previously. In the following example, 
the generation index D is built on the control volume whose serial 
number is 000045. The higher level indexes A.B.C already exist. When 
the number of generation data sets in the generation index D exceeds 
four, the oldest data set in the group is uncataloged and scratched. 



Name 



Ope rati on j Operand 



| INDEX | GENINDX 
Check Exceptional Returns 
GENINDX | CAMLST | BLDG,DLEVEL,VOLNUM, , DELETE, , 4 



BUILD GENERATION INDEX 



DLEVEL 
VOLNUM 



DC 
DC 



CLS^.B.C.D' 
CL6 , 000045 I 



BLANK DELIMITER 



The INDEX macro instruction points to the CAMLST macro instruction. 
BLDG, the first operand of CAMLST, specifies that a generation index be 
built. DLEVEL, the second operand, specifies the main storage location 
of an area into which you have placed the fully qualified name of a 
generation index. VOLNUM, the third operand, specifies the main storage 
location of an area into which you have placed the 6-byte serial number 
of the volume on which the generation index is to be built. DELETE, the 
fifth operand, specifies that all data sets dropped from the generation 
data group are to be deleted. The final operand, 4, specifies the 
number of data sets that are to be maintained in the generation data 
group. 

HOW TO DELETE AN INDEX 

You can delete any number of index levels from an existing index 
structure. Each level of the index is deleted separately. Generation 
indexes are also removed this way. (You can also delete index levels 
automatically when they are no longer needed. See "How to Remove Data 
Set References from the Catalog" in this chapter for details.) You 
delete each level of the index by using the INDEX and CAMLST macro 
instructions . 

If an index level either has an alias, or has other index levels or 
data sets cataloged under it, it cannot be deleted. 

Example ; In the following example, index level C is deleted from index 
structure A.B.C. The search for the index level starts on the system 
residence volume. 



■t t 

| Operation! Operand 



Name 



H 



| | INDEX j DELETE 
| Check Exceptional Returns 
j DELETE | CAMLST | DLTX,LEVELC 
j LEVELC | DC | CL6* A.B.C* 
L J. X 



DELETE INDEX LEVEL C FROMJ 
INDEX STRUCTURE A.B.C j 

I 
ONE BLANK FOR DELIMITER | 



The INDEX macro instruction points to the CAMLST macro instruction. 
DLTX, the first operand of CAMLST, specifies that an index level be 
deleted. LEVELC, the second operand, specifies the main storage 
location of an area into which you have placed the fully qualified name 
of the index structure whose lowest level is to be deleted. 
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HOW TO ASSIGN AN ALIAS 



You assign an alias to an index level by using -the INDEX and CAMLST 
macro instructions. An alias can be assigned only to a high level 
index; e.g., index A of index structure A.B.C can have an alias, but 
index B cannot. Assigning an alias to a high level index effectively 
provides aliases for all data sets cataloged under that index. An alias 
cannot be assigned to a generation index with only one level. 




Example : In the following example, index level A is assigned an alias 
of X. The search for the index level starts on the system residence 
volume . 



Name 



| Operation! Operand 



l + + 1 

BUILD AN ALIAS FOR A HIGH| 
LEVEL INDEX 

MUST BE 8-BYTE FIELDS 



| INDEX | ALIAS 
Check Exceptional Returns 
ALIAS | CAMLST | BLDA, DS NAME, ,DS ALIAS 
DSNAME | DC j CLS'A* 

DSALIAS | DC | CL8'X" 
.JL JL. 



L JL JL J 



The INDEX macro instruction points to the CAMLST macro instruction. 
BLDA, the first operand of CAMLST, specifies that an alias be built. 
DSNAME, the second operand, specifies the main storage location of an 
8-byte area into which you have placed the name of the high level index 
to be assigned an alias. DSALIAS, the fourth operand, specifies the 
main storage location of an 8-byte area into which you have placed the 
alias to be assigned. 



HOW TO DELETE AN ALIAS 

You delete an alias previously assigned to a high level index by using 
the INDEX and CAMLST macro instructions. 



Example : In the following example, alias X, previously assigned as an 
alias for index level A, is deleted. The search for the alias starts on 
the system residence volume. 



- T T 

| Ope rati on | Operand 
_ + + 



| Name 

L 



| | INDEX | DELALIAS 

| Check Exceptional Returns 
| DELALIAS | CAMLST | DLTA, ALIAS 
| ALIAS | DC | CL8'X' 

L X X 



DELETE AN ALIAS FOR A 
HIGH LEVEL INDEX 

MUST BE 8-BYTE FIELD 



The INDEX macro instruction points to the CAMLST macro instruction. 
DLTA, the first operand of CAMLST, specifies that an alias be deleted. 
ALIAS, the second operand, specifies the main storage location of an 
8-byte area into which you have placed the alias to be deleted. 
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HOW TO CONNECT CONTROL VOLUMES 

You connect two control volumes by using the INDEX and CAMLST macro 
instructions . If a control volume is to be connected to the system 
residence volume, you need supply only the serial number of the volume 
to be connected and the name of a high level index associated with the 
volume to be connected. 

If a control volume is to be connected to a control volume other than 
the system residence volume, you must supply the serial numbers of both 
volumes and the name of a high level index associated with the volume to 
be connected . 

The result of connecting control volumes is that the volume serial 
number of the control volume connected and the name of a high level 
index are entered into the volume index of the volume to which it was 
connected. This entry is called a control volume pointer. 

Example : In the following example, the control volume whose serial 
number is 001555 is connected to the control volume numbered 000155. 
The name of the high level index is HIGHINDX. 



"T T 

| Operation] Operand 



Name 



| INDEX | CONNECT CONNECT TWO CON- 

Check Exceptional Returns TROL VOLUMES WHOSE 

CONNECT j CAMLST | LNKX,INDXNAME,OLDCVOL,NEWCVOL SERIAL NUMBERS ARE 

DC j CLS'HIGHINDX* 000155 AND 001555. 

DC | CL6'000155' 

DC | X' 30002001* 2311 DISK STORAGE 

DC I CL6' 001555' 



* 



INDXNAME | 
OLDCVOL j 
NEWCVOL I 



The INDEX macro instruction points to the CAMLST macro instruction. 
LNKX, the first operand of CAMLST, specifies that control volumes be 
connected. INDXNAME, the second operand, specifies the main storage 
location of an 8-byte area into which you have placed the name of the 
high level index of the volume to be connected. OLDCVOL, the third 
operand, specifies the main storage location of a 6-byte area into which 
you have placed the serial number of the volume to which you are 
connecting. NEWCVOL, the fourth operand, specifies the main storage 
location of a 10-byte area into which you have placed the 4-byte binary 
device code of the volume to be connected followed by the 6-byte area to 
contain the volume serial number of the volume to be connected. 



HOW TO DISCONNECT CONTROL VOLUMES 

You disconnect two control volumes by using the INDEX and CAMLST macro 
instructions. If a control volume is to be disconnected from the system 
residence volume, you need supply only the name of the high level index 
associated with the volume to be disconnected. 

If a control volume is to be disconnected from a control volume other 
than the system residence volume, you must supply, in addition to the 
name of the high level index, the serial number of the control volume 
from which you want to disconnect. 

The result of disconnecting control volumes is that the control 
volume pointer is removed from the volume index of the volume from which 
you are disconnecting. 
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Example : In the following example, the control volume that contains the 
high level index HIGHINDX is disconnected from the system residence 
volume . 



| Name 
j. 



_ T T 

| Operation | Operand 



| INDEX | DISCNECT 
| Check Exceptional Returns 
| DISCNECT | CAMLST | DRPX, INDXNAME 
J INDXNAME | DC j CL8 'HIGHINDX' 
L L X 



DISCONNECT TWO CONTROL VOLUMES 



MUST BE 8-BYTE FIELD 




—J 



The INDEX macro instruction points to the CAMLST macro instruction. 
DRPX, the first operand of CAMLST, specifies that control volumes be 
disconnected. INDEXNAME, the second operand, specifies the main storage 
location of an 8-byte area into which you have placed the name of the 
high level index of the control volume to be disconnected. 



HOW TO CATALOG A DATA SET 

You catalog a data set by using the CATALOG and CAMLST macro 
instructions . The CATALOG macro instruction points to the CAMLST macro 
instruction; parameters of the CAMLST macro instruction specify the 
options for cataloging a data set. When the CAT parameter is used, all 
index levels required to catalog the data set must exist in the catalog. 
The index structure need not exist when the CATBX parameter is used; any 
missing index levels are automatically created. 

You must build a complete volume list in main storage. This volume 
list consists of volume pointers for all volumes on which the data set 
is stored. The first two bytes of the list indicate the number of 
volume pointers that follow. Each 12-byte volume pointer consists of a 
4- byte device code, a 6-byte volume serial number, and a 2-byte data set 
sequence number. The sequence number is always zero for direct access 
volumes. (Device codes are contained in Appendix B of this chapter.) 

-When Index Levels Exist 

When the index levels already exist for a data set, you can use the CAT 
parameter of the CAMLST macro instruction to catalog the data set. 
Missing index levels cause an exceptional return code to be set. 

Example : In the following example, the data set named A.B.C is 
cataloged under an existing index structure A.B. The data set is stored 
on two volumes. 



Name 



-T T 

| Operation | Operand 





1 


CATALOG 


| ADDABC 


| Check Excepti 


onal Returns 


| ADDABC 


1 


CAMLST 


| CAT , DSNAME , , VOLUMES 


| DSNAME 


1 


DC 


| CL6'A.B.C' 


| VOLUMES 


1 


DC 


| H'2" 




1 


DC 


| X'30002001' 




1 


DC 


| CL6'000014' 




1 


DC 


| H'O* 




1 


DC 


| X'30002001" 




1 


DC 


| CL6'000015' 




1 


DC 


| H'O' 


L 


1 




J. 



CATALOG DATA SET A.B.C. THE 
INDEX STRUCTURE A.B. EXISTS 

ONE BLANK FOR DELIMITER 
TWO VOLUMES 
2311 DISK STORAGE 
VOLUME SERIAL NUMBER 
DATA SET SEQUENCE NUMBER 
2311 DISK STORAGE 
VOLUME SERIAL NUMBER 
SEQUENCE NUMBER 



—J 
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The CATALOG macro instruction points to the CAMLST macro instruction. 
CAT, the first operand of CAMLST, specifies that a data set be 
cataloged. DSNAME, the second operand, specifies the main storage 
location of an area into which you have placed the fully qualified name 
of the data set to be cataloged. VOLUMES, the fourth operand, specifies 
the main storage location of the volume list you have built. 

-By Creating Required Index Levels 

When index levels are missing, you can use the CATBX parameter of the 
CAMLST macro instruction to automatically create them before cataloging 
the data set. 

Example : In the following example, the index structure A.B is created 
and data set A.B.C is cataloged. The data set is stored on one volume. 



t r 

| Operation! Operand 



Name 



-■f 



1 1 


CATALOG 


1 CTBXABC 


| Check Exceptional Returns 


| CTBXABC | 


CAMLST 


| CATBX, DSNAM 


j DSNAME | 


DC 


j CLe'A.B.C* 


| VOLUMES | 


DC 


| H"l' 


1 i 


DC 


| X , 30002001 i 


i 1 


DC 


1 cLe'oooois 1 


1 1 


DC 


| H'0» 


j TTR | 


DC 


1 xLa'oooioa* 



CATALOG DATA SET A.B.C 
CREATE NEEDED INDEX LEVELS 
)LUMES ,DSCBTTR=TTR 
ONE BLANK FOR DELIMITER 
ONE VOLUME 
2311 DISK STORAGE 
VOLUME SERIAL NUMBER 
DATA SET SEQUENCE NUMBER 
TTR OF DSCB IN VTOC 



The CATALOG macro instruction points to the CAMLST macro instruction. 
CATBX, the first operand of CAMLST, specifies that a data set is to be 
cataloged and any required higher level indexes are to be created. 
DSNAME, the second operand, specifies the main storage location of an 
area into which you have placed the fully qualified name of the data set 
to be cataloged. VOLUMES, the third operand, specifies the main storage 
location of the volume list you have built. DSCBTTR=TTR, the fourth 
operand, specifies the main storage location into which you have placed 
the relative track address of the DSCB for the data set to be cataloged. 
The DSCBTTR operand is optional and is ignored for data sets residing on 
more than one volume. 



HOW TO REMOVE DATA SET REFERENCES FROM THE CATALOG 

You remove data set references from the catalog by using the CATALOG and 
CAMLST macro instructions. Two options are available: simply remove 
references, or remove references and delete any indexes that are no 
longer needed. 

-Uncataloq and Retain Index Levels 

When the UNCAT operand of the CAMLST macro instruction is used, a data 
set reference is removed, but all index levels are retained. 

Example : In the following example, references to data set A.B.C are 
removed from the catalog. 
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Name 



I Operation! Operand 



| | CATALOG | REMOVE 

I Check Exceptional Returns 

| REMOVE | CAMLST | UNCAT, DSNAME 

j DSNAME j DC j CL6 1 A.B.C 

L J. X 



j 

REMOVE REFERENCES TO DATA j 
SET A.B.C FROM THE CATALOG j 

I 
ONE BLANK FOR DELIMITER I 



The CATALOG macro instruction points to the CAMLST macro instruction. 
UNCAT, the first operand of CAMLST, specifies that references to a data 
set be removed from the catalog. DSNAME, the second operand, specifies 
the main storage location of an area into which you have placed the 
fully qualified name of the data set whose references are to be removed. 




-Uncatalog and Remove Index Levels 



When the UNCATDX operand of the CAMLST macro instruction is used, a data 
set reference and unneeded indexes, with the exception of the 
highest- level index, are removed from the catalog. 

Example : In the following example, references to data set A.B.C are 
removed from the catalog. Index B is removed unless it contains 
references to other data sets. Index A remains because it is the 
highest level index. 



"T " T 

| Operation | Operand 



| Name 

I- 

I 



+ + 

| CATALOG | RMDSNNDX 
Check Exceptional Returns 
RMDSNNDX | CAMLST | UCATDX, DSNAME 
DSNAME j DC j CL6*A.B.C 

-L X 



REMOVE REFERENCES TO DATA 
SET A.B.C FROM THE CATALOG 
AND REMOVE INDEXES 
ONE BLANK FOR DELIMITER 



The CATALOG macro instruction points to the CAMLST macro instruction. 
UNCATDX, the first operand, specifies that references to a data set be 
removed from the catalog. DSNAME, the second operand, specifies the 
main storage location of an area into which you have placed the fully 
qualified name of the data set whose references are to be removed. 



HOW TO RECATALOG A DATA SET 

You recatalog a cataloged data set by using the CATALOG and CAMLST macro 
instructions. Recataloging is usually performed when new volume 
pointers must be added to the volume list of a data set. 

You must build a complete volume list in main storage. This volume 
list consists of volume pointers for all volumes on which the data set 
is stored. The first two bytes of the list indicate the number of 
volume pointers that follow. Each 12-byte volume pointer consists of a 
U-byte device code, a 6-byte volume serial number, and a 2-byte data set 
sequence number. The sequence number is always zero for direct access 
volumes. (Device codes are contained in Appendix B of this chapter.) 

Example : In the following example, the data set named A.B.C is 
recataloged. A new volume pointer is added to the volume list, which 
previously contained only two volume pointers. 
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Name 



j Operation! Operand 
+ + 

j CATALOG | RECATLG 
Check Exceptional Returns 



RECATLG j CAMLST | RECAT , DSNAME, , VOLUMES 



DSNAME 


| DC 


| CL6'A.B.C 


VOLUMES 


| DC 


| H'3' 




j DC 


| X'30002001' 




| DC 


| CL6 '000014' 




| DC 


| H'O' 




| DC 


| X'30002001* 




| DC 


| CL6'000015» 




| DC 


| H'O' 




| DC 


| X'30002001» 




| DC 


| CL6'000016» 




| DC 


| H'O' 



RE CATALOG DATA SET A.B.C, 
ADDING A NEW VOLUME 
POINTER TO THE VOLUME 
LIST. 

ONE BLANK FOR DELIMITER 
THREE VOLUMES 
2311 DISK STORAGE 
VOLUME SERIAL NUMBER 
SEQUENCE NUMBER 
2311 DISK STORAGE 
VOLUME SERIAL NUMBER 
SEQUENCE NUMBER 
2311 DISK STORAGE 
VOLUME SERIAL NUMBER 
SEQUENCE NUMBER 



The CATALOG macro instruction points to the CAMLST macro instruction. 
RECAT, the first operand of CAMLST, specifies that a data set be 
recataloged. DSNAME, the second operand, specifies the main storage 
location of an area into which you have placed the fully qualified name 
of the data set to be recataloged. VOLUMES, the fourth operand, 
specifies the main storage location of the volume list you have built. 

HOW TO READ A DATA SET CONTROL BLOCK FROM THE VOLUME TABLE OF CONTENTS 

You can read a data set control block (DSCB) into main storage by using 
the OBTAIN and CAMLST macro instructions. There are two ways to specify 
the DSCB that you want read: by using the name of the data set 
associated with the DSCB, or by using the absolute track address of the 
DSCB. 

When you specify the name of the data set, a format 1 (identifier) 
DSCB is read into main storage. To read a DSCB other than a format 1 
DSCB, you must specify an absolute track address. (DSCB formats and 
field descriptions are contained in the System Control Block 
publication) . 

When a data set name is specified, the 9 6 -byte data portion of the 
format 1 DSCB, and the absolute track address of the DSCB are read into 
main storage. When the absolute track address of a DSCB is specified, 
the 4 4 -byte key portion and the 9 6 -byte data portion of the DSCB are 
read into main storage. 

Example ; In the following example, the format 1 DSCB for data set A.B.C 
is read into main storage. The serial number of the volume containing 
the DSCB is 770655. 



■T T 

| Operation | Operand 



| Name 
j. 



-+- 



| OBTAIN | DSCBABC 
Check Exceptional Returns 



READ DSCB FOR DATA 
SET A.B.C INTO MAIN 



DSCBABC | CAMLST J SEARCH ,DSABC,VOLNUM,WORKAREA STORAGE AREA NAMED 

DSABC j DC j CLU^'A.B.C WORKAREA. 96-BYTE 

VOLNUM j DC j CL6 '770655' DATA PORTION IS 

WORKAREA j DS | 0D READ. THE REST OF 

j DS | 148C THE AREA IS USED BY 

I I THE OBTAIN ROUTINE 
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The OBTAIN macro instruction points to the CAMLST macro instruction. 
SEARCH, the first operand of CAMLST, specifies that a DSCB be read into 
main storage. DSABC, the second operand, specifies the main storage 
location of a 44-byte area into which you have placed the fully 
qualified name of the data set whose associated DSCB is to be read. 
VOLNUM, the third operand, specifies the main storage location of a 
6-oyte area into which you have placed the serial number of the volume 
containing the required DSCB. WORKAREA, the fourth operand, specifies 
the main storage location of a 14 8-byte work area that is to contain the 
DSCB. 

After execution of these macro instructions, the first 9 6 bytes of 
the work area contain the data portion of the format 1 DSCB; the next 
five bytes contain the absolute track address of the DSCB. 



HOW TO DELETE A DATA SET 

You delete a data set stored on direct access volumes by using the 
SCRATCH and CAMLST macro instructions. This causes all data set control 
blocks (DSCB) for the data set to be deleted, and all space occupied by 
the data set to be made available for reallocation. If the data set to 
be deleted is sharing a split cylinder, the space will not be made 
available for reallocation until all data sets on the split cylinder are 
deleted. 

A data set cannot be deleted if the expiration date in the format 1 
(identifier) DSCB has not passed, unless you choose to ignore the 
expiration date. You can ignore the expiration date by using the OVRD 
option in the CAMLST macro instruction. 

If a data set to be deleted is stored on more than one volume, either 
a device must be available on which to mount the volumes , or at least 
one volume must be mounted. In addition, all other required volumes 
must be serially mountable. Certain volumes, such as the system 
residence volume, must always be mounted. 

When deleting a data set, you must build a complete volume list in 
main storage. This volume list consists of volume pointers for all 
volumes on which the data set is stored. The first two bytes of the 
list indicate the number of volume pointers that follow. Each 12-byte 
volume pointer consists of a 4 -byte device code, a 6-byte volume serial 
number, and a 2-byte scratch status code. (Device codes are contained 
in Appendix B of this chapter.) 

Volumes are processed in the order that they appear in the volume 
list. Those volumes that are pointed to at the beginning of the list 
are processed first. If a volume is not mounted, a message is issued to 
the operator requesting him to mount the volume. This is done if you 
indicate the I/O device on which unmoumted volumes are to be mounted by 
loading register zero with the address of the UCB associated with the 
device to be used. If you do not load register zero with the UCB 
address, its contents must be zero, and the first volume in the volume 
list must be mounted before the SCRATCH macro instruction is executed. 

If the operator cannot mount the requested volume, he issues a reply 
indicating that he cannot fulfill the request. A condition code is then 
set in the last byte of the volume pointer (the second byte of the 
scratch status code) for the unavailable volume, and the next volume 
indicated in the volume list is processed or requested. 

Example ; In the following example, data set A.B.C is deleted from two 
volumes. The expiration date in the format 1 DSCB is ignored. 
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r t t t 

| Name | Operation J Operand | 

j. + + j 



i i sr i 0,0 


SET REG TO ZERO j 


| j SCRATCH | DELABC 


DELETE DATA SET j 


J Check Exceptional Returns 


A. B.C. FROM TWO j 


| DELABC | CAMLST | SCRATCH, DSABC, , VOLIST , ,OVRD 


VOLUMES, IGNORING | 


| DSABC j DC | CIW'A.B.C 


THE EXPIRATION | 


| VOLIST j DC j H'2' 


DATE IN THE DSCB. j 


j | DC | X , 30002001 t 


2311 DISK STORAGE j 


| j DC | CLe'OOOOl? 1 


VOLUME SERIAL NO. | 


| I DC 1^0' 


SCRATCH STATUS CODE| 


| | DC | X»30002001* 


2311 DISK STORAGE | 


| | DC j CL6' 000018' 


VOLUME SERIAL NO. j 


| | DC j H'0' 


SCRATCH STATUS CODE| 


L J. J. 


J 



The SCRATCH macro instruction points to the CAMLST macro instruction. 
SCRATCH, the first operand of CAMLST, specifies that a data set be 
deleted. DSABC, the second operand, specifies the main storage location 
of a 44-byte area into which you have placed the fully qualified name of 
the data set to be deleted. VOLIST, the fourth operand, specifies the 
main storage location of the volume list you have built. OVRD, the 
sixth operand, specifies that the expiration date be ignored in the DSCB 
of the data set to be deleted. 



HOW TO RENAME A DATA SET 

You rename a data set stored on direct access volumes by using the 
RENAME and CAMLST macro instructions. This causes the data set name in 
I all identifier (format 1) data set control blocks (DSCB) for the data 
set to be replaced by the new name that you supply. 

If a data set to be renamed is stored on more than one volume, either 
a device must be available on which to mount the volumes , or at least 
one volume must be mounted. In addition, all other required volumes 
must be serially mountable. Certain volumes, such as the system 
residence volume, must always be mounted. 

When renaming a data set, you must build a complete volume list in 
main storage. This volume list consists of volume pointers for all 
volumes on which the data set is stored. The first two bytes of the 
list indicate the number of volume pointers that follow. Each 12-byte 
volume pointer consists of a 4-byte device code, a 6-byte volume serial 
| number, and a 2-byte rename status code. (Device codes are contained in 
Appendix B of this chapter.) 

Volumes are processed in the order they appear in the volume list. 
Those volumes that are pointed to at the beginning of the list are 
processed first. If a volume is not mounted, a message is issued the 
operator requesting him to mount the volume. This is done if you 
indicate the I/O device on which unmounted volumes are to be mounted by 
loading register zero with the address of the UCB associated with the 
device to be used. If you do not load register zero with the UCB 
address, its contents must be zero, and the first volume in the volume 
list must be mounted before the RENAME macro instruction is executed. 

If the operator cannot mount the requested volume, he issues a reply 
indicating that he cannot fulfill the request. A condition code is then 
set in the last byte of the volume pointer (the secondary byte of the 
rename status code) for the unavailable volume, and the next volume 
indicated in the volume list is processed or requested. 
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Example ; In the following example, data set A.B.C is renamed D. E.F. 
The data set extends across two volumes. 



Name 



■t r 

| Operation | Operand 



| SR | 0,0 
| RENAME | DSABC 
Check Exceptional Returns 



SET REG TO ZERO 
CHANGE DATA SET 
NAME A.B.C. TO 



DSABC | CAMLST | RENAME , OLDNAME , NEWNAME , VOLI ST D.E.F 

OLDNAME | DC | CL4U , A.B.C t 

NEWNAME j DC | CLUa'D.E.F' 

VOLI ST | DC j H'2' TWO VOLUMES 

| DC | X* 30002001* 2311 DISK STORAGE 

j DC j CL6* 000017 ■ VOLUME SERIAL NO. 

| DC | B'0' RENAME STATUS CODE 

| DC j X' 30002001* 2311 DISK STORAGE 

I DC j CL6* 000018* VOLUME SERIAL NO. 

I DC I H'O' RENAME STATUS CODE 




The RENAME macro instruction points to the CAMLST macro instruction. 
RENAME, the first operand of CAMLST, specifies that a data set be 
renamed. OLDNAME, the second operand, specifies the main storage 
location of a 44-byte area into which you have placed the fully 
qualified name of the data set to be renamed. NEWNAME, the third 
operand, specifies the main storage location of a 44-byte area into 
which you have placed the new name of the data set. VOLIST, the fourth 
operand, specifies the main storage location of the volume list you have 
built. 



How to Share Space on a Volume Initialized Under DOS 



With the addition to the OS DADSM allocation program of a routine to 
convert a DOS format VTOC to an OS format VTOC, it is now possible to 
share the space on such a volume (one initialized under DOS) between 
data sets written by users using DOS and users using OS. The degree and 
limits of sharing are: 

• The OS user may now request space in any standard OS form of space 
allocation, that is: TRK, CYL, average block size, and ABSTR. 

• The OS stand-alone utility program IBCRCVRP does not accept 
alternate track assignment made under DOS. If the volume has any 
alternate tracks assigned under DOS, and additional alternate tracks 
must be assigned, the DOS assign alternate track program must be 
used to perform that function. 

The net effect is that OS and DOS may share a volume, but the data sets 
written under each system can only be read under the system under which 
they were written. 
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Appendix A: Catalog Block Entries 

This section describes the contents of all catalog entries. 
Control Entries 

A volume index control entry is always the first entry in a volume 
index. The volume index control entry is 22 bytes long and contains 
eight fields. 

Field 1 ; Name field (8 bytes) — contains only a binary one to ensure 
that this entry is the first entry in the first block of the index. 

Field 2 : Last block address (3 bytes) — contains the relative track 
address of the last block in the volume index. The address is in the 
form TTR. 

Field 3 ; Halfword count (1 byte) — contains a binary five to indicate 
that five half words follow. 

Field 4 : Catalog upper limit (3 bytes) — contains the relative track 
address of the last block in the catalog data set. The address is in 
the form TTR. 

Field 5 ; Zero field (1 byte) — contains binary zeros. 

Field 6 ; First available block address (3 bytes) — contains the 
relative track address of the unused block in the catalog that is 
closest to the beginning of the catalog data set. 

Field 7 : Zero field (1 byte) — contains binary zeros. 

Field 8 : Unused bytes in last block (2 bytes) — contains the binary 
count of the number of unused bytes in the last block of the volume 
index. 

An index control entry is the first entry in all indexes except 
volume indexes. The index control entry is 18 bytes long and contains 
six fields. 

Field 1 : Name field (8 bytes) — contains only a binary one to ensure 
that this entry, because it has the lowest binary name value, is the 
first entry in the first block of the index. 

Field 2 : Last block address (3 bytes) — contains the relative track 
address of the last block assigned to the index. The address is in the 
form TTR. 

Field 3 : Halfword count (1 byte) — contains a binary three to indicate 
that three half words follow. 

Field 4 ; Index lower limit (3 bytes) — contains the relative track 
address of the block in which this entry appears. The address is in the 
form TTR. 

Field 5 : Number of aliases (1 byte) — contains the binary count of the 
number of aliases assigned to the index. If the index is not a high 
level index, this field is zero. 

Field 6 : Unused bytes in last block (2 bytes) — contains the binary 
count of the number of unused bytes remaining in the last block of the 
index. 
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An index link entry is the last entry in all index blocks. The entry 
is 12 bytes long and contains three fields. 

Field 1 ; Name field (8 bytes) — contains only the hexadecimal number 
FF to ensure that this entry, because it has the highest binary name 
value, will appear as the last entry in any index block. 

Field 2 ; Link address (3 bytes) — contains the relative track address 
of the next block of the same index, if there is a next block in the 
index. Otherwise, the field contains binary zeros. 

Field 3 : Halfword count (1 byte) — contains a binary zero to indicate 
that no additional fields follow. 

Pointer Entries 

An index pointer entry can appear in all indexes except generation 
indexes. The entry is 12 bytes long and contains three fields. 

j Field 1 ; Name field (8 bytes) — contains the name of the index being 
pointed to by field 2. 

Field 2 : Index address (3 bytes) — contains the relative track address 
of the first block of the index named in field 1. The address is in the 
form TTR. 

Field 3 ; Halfword count (1 byte) — contains a binary zero to indicate 
that no additional fields follow. 

A data set pointer entry can appear in any index. It contains the 
simple name of a data set and from one to five 12-byte fields that each 
identify a volume on which the named data set resides. If the data set 
resides on more than five volumes, a volume control block must be used 
to point to the volumes. The volume control block is identified by a 
volume control block pointer entry, not a data set pointer entry. 

The data set pointer entry varies in length. The length is 
determined by the formula (14+12m), where m is the number of volumes 
containing the data set. The variable m can be from 1 through 5. The 
data set pointer entry can appear in any index, and it contains five 
fields. 

Field 1 : Name field (8 bytes) — contains the simple name of the data 
set whose volumes are identified in field 5. 

Field 2 : DSCB TTR (3 bytes) — contains the track address (TTR) of the 
data set control block if the data set resides on only one volume. If 
the data set resides on more than one volume, this field contains a 
binary zero. 

Field 3 : Halfword count (1 byte) — contains the binary count of the 
number of half words that follow. The number is found by the formula 
(6m+l), where m is the number of volumes on which the data set resides. 
The variable m can be from 1 through 5. 

Field 4 ; Volume count (2 bytes) — contains the binary count of the 
number of volumes identified in field 5 of this entry. 

Field 5 ; Volume entries (12 to 60 bytes) — contains from one to five 
12-byte entries, each of which identifies a volume on which the data set 
resides. Each entry contains a 4 -byte device code, a 6-byte volume 
serial number, and a 2-byte data set sequence number. The data set 
sequence number is zero for direct access volumes. 
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A volume control block pointer entry can appear in any index. It can 
identify up to 20 volumes. The entry is 14 bytes long and contains four 
fields. 

Field 1 : Name field (8 bytes) — contains the last name of the 
qualified name of the data set identified by this entry. The data set 
resides on the volumes whose serial numbers are given in the volume 
control block pointed to by field 2. 

Field 2 : Address field (3 bytes) — contains the relative track address 
of the volume control block identifying the volumes containing the data 
set named in field 1. The address is in the form TTR. 

Field 3 ; Ha If word count (1 byte) — contains a binary one to indicate 
that one half word follows. 

Field 4 : Zero field (2 bytes) — contains binary zeros. 

A control volume pointer entry can appear only in volume indexes. It 
is 18 bytes long and contains four fields. 

Field 1 : Name field (8 bytes) — contains a high level index name that 
appears in the volume index of the control volume identified in field 4. 

Field 2 ; Address field (3 bytes) — contains binary zeros. 

Field 3 : Halfword count (1 byte) — contains a binary three to indicate 
that three half words follow. 

Field 4 : Control volume serial number (6 bytes) — contains the serial 
number of the control volume whose volume index contains an entry 
identifying the high level index name in field 1. 

A new control volume pointer entry can appear only in volume indexes. 
It is 22 bytes long and contains 5 fields. 

Field 1 : Name field (8 bytes) contains a high level index name that 
appears in the volume index of the control volume identified in fields 4 
and 5. 

Field 2 ; Address field (3 bytes) contains binary zeros. 

Field 3 ; Halfword count 41 byte) contains a binary 5 to indicate that 
five ha If words follow. 

Field 4 : Control volume device code (4 bytes) contains the 4-byte 
binary device code of the control volume whose index contains an entry 
identifying the high level index name in field 1. 

Field 5 ; Control volume serial number (6 bytes) contains the serial 
number of the control volume whose index contains an entry identifying 
the high level index name in field 1. 

An alias entry can appear in volume indexes only. An alias entry is 
20 bytes long and contains four fields. 

Field 1 : Name field (8 bytes) — contains the alias of the high level 
index identified in field 2. 

Field 2 : Address field (3 bytes) — contains the relative track address 
of the first block of the index named in field 4. The address is in the 
form TTR. 
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Field 3 ; Half word count (1 byte) — contains a binary four to indicate 
that four half words follow. 

Field 4 ; True name field (8 bytes) — contains the name of the index 
whose alias appears in field 1. The address of the index is in field 2. 

A generation index pointer entry can appear in all indexes except 
generation indexes. The entry is 16 bytes long and contains six fields. 

Field 1 : Name field (8 bytes) — contains the name of the generation 
index whose address is contained in field 2. 

Field 2 ; Address field (3 bytes) — contains the relative track address 
of the generation index named in field 1. The address is in the form 
TTR. 

Field 3 ; Half word count (1 byte) — contains a binary two to indicate 
that two half words follow. 

Field 4 : Flags (1 byte) — contains flags that govern the uncataloging 
of data sets as specified by the DELETE and EMPTY options of the INDEX 
macro instruction. The options and their hexadecimal codes are as 
follows : 

EMPTY=01 DELETE=02 EMPTY and DELETE=03 

Field 5 : Maximum generations allowed (1 byte) — contains the binary 
count of the maximum number of generations allowed in the index at one 
time as specified in the INDEX macro instruction. 

Field 6 ; Current generation count (2 bytes) — contains the binary 
count of the number of generations cataloged in the index. 

The Volume Control Block Contents 

A volume control block is composed of one or more volume-list blocks. 
Each volume- list block contains an 8-byte key and a 256-byte data 
portion. The data portion of the volume-list block can identify up to 
20 volumes on which a data set is recorded. The format of the volume 
list block is as follows: 

Field 1 ; Number of volumes (2 bytes) — the first volume- list block 
contains the binary count of volumes on which the data set is stored; 
the value of this field is reduced by 20 for each subsequent volume- list 
block. If a data set is on 61 volumes, for example, it has four 
volume-list blocks. The first field of each block contains 61,41,21, 
and 1, respectively. 

Field 2 : Volume identification (12 to 240 bytes) — contains from 1 to 
20 12-byte entries, each of which identifies a volume on which the data 
set resides. Each entry contains a 4-byte device code, a 6-byte volume 
serial number, and a 2-byte data set sequence number. The data set 
sequence number is zero for direct access volumes. 

Field 3 : Zero field (10 bytes) — contains binary zeros. 

Field 4 ; Chain address (3 bytes) — contains the relative track address 
of the next block of this volume control block, if additional blocks 
exist. The address is in the form TTR. If this is the last block of 
the volume control block, the field contains a binary zero. If this 
field is not zero, this block must contain twenty 12-byte fields 
identifying volumes of the data set. 

Field 5 ; Zero field (1 byte) — contains binary zeros. 
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Appendix B: Device Code Designations 



Device 

IBM 2400 Series Magnetic 
Tape Units 

IBM 2400 Series Magnetic 
Tape Units 

IBM 2400 Series Magnetic 
Tape Units 

IBM 2400 Series Magnetic 
Tape Units 

IBM 2400 Series Magnetic 
Tape Units 

IBM 2311 Disk Storage Drive 

IBM 2301 Drum Storage 

IBM 2302 Disk Storage 

IBM 2303 Drum Storage 

IBM 2314 Direct Access 
Storage Facility 

IBM 2321 Data Cell 

IBM 2305 Fixed Head 
Storage Model 1 

IBM 2305 Fixed Head 
Storage Model 2 

IBM 3330 Disk Storage 

IBM 3400 Series Magnetic 
Tape Units 

IBM 3400 Series Magnetic 
Tape Units 

IBM 3400 Series Magnetic 
Tape Units 



Features 



7-track Compatibility 

7-track Compatibility 
Data Conversion 



Phase Encoding 

Phase Encoding 
with Dual Density 



Phase Encoding 

Phase Encoding 
with Dual Density 



7-track 



Device Code 
Designation 
(In Hexadecimal) 



30008001 

30808001 

30C08001 

34008001 

34208001 
30002001 
30402002 
30002004 
30002003 

30C02008 
30002005 

30002006 

30002007 
30502009 

34008003 

34208003 

34C08003 



Note : These and other device codes are also enumerated under the 
DEVTYPE macro instruction in the chapter: "System Macro Instructions. 
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IECDSECT, IEFJFCBN, and 
IEFUCBOB Macro Instructions 



If you want to use the IECDSECT, IEFJFCBN, 
and IEFUCBOB macro instructions, you must 
either add these macro definitions to the 
macro library (SYS1.MACLIB) or place them 
in a separate partitioned data set and 
concatenate this data set to the macro 
library. 

This chapter contains the following: 

• The format of the macro instructions. 

• The job control and utility statements 
needed to add the macro instructions to 
the library . 

• The macro definition to be added to the 
library. 

The information previously contained in 
this chapter on label handling routines may 
be found in the publication IBM System/ 360 
Operating System: Tape Labels , GC28-6680. 




IECDSECT, IEFJFCBN, and IEFUCBOB Macro Instructions 35 



IECDSECT Macro Instruction 

This macro instruction defines the symbolic names of fields in the work 
area used by the OPEN, CLOSE, TCLOSE, and EOV routines. Consult IBM 
System/360 Operating System; Input/Output Support (OPEN/CLOSE/EOV) 
Program Logic Manual , GY28-6609, for a description of the IECDSECS macro 
instruction which defines additional fields in the work area. Code this 
macro instruction with blank name and operand fields, and precede it 
with a DSECT statement. Note : The IEFJFCBN macro instruction is used 
in the assembly of IECDSECT. The macro definition for IEFJFCBN must be 
present in the macro-library (SYSl.MACLIB) for successful definition of 
all fields in the work area. 



r t t 

| Name | Operation | Operand 

j. + 4 

I J IECDSECT J 

L 1 x 



— 1 
I 

H 

I 
—j 



Control Statements Required 



// jobname 

//stepname 

//SYSPRINT 

//SYSUT2 

//SYSIN 

./ ADD 



JOB {parameters} 

EXEC PGM=IEBUPDTE,PARM=NEW 

DD SYSOUT=A 

DD DSNAME=SYS1.MACLIB,DISP=0LD 

DD DATA 

NAME=IECDSECT , LIST=ALL 



IECDSECT Macro definition 



./ 
/* 



ENDUP 



IECDSECT Macro Definition 



MACRO 
IECDSECT 
SPACE 1 



SPACE 1 



SPACE 1 



THIS MACRO IS USED TO DEFINE THE WORK AREA 
FOR ALL MODULES OF OPEN, CLOSE, TCLOSE 
AND END OF VOLUME FOR O/S 360 

THIS MACRO DEFINES A WORK AREA WITH THE 
FOLLOWING FORMAT 

1. LABELS AND DSCB 
LABELS 

VOLUME LABEL 

FILE LABEL 1 

FILE LABEL 2 
DSCB 

FORMAT 1 

FORMAT 3 KEY 

FORMAT 3 DATA 

CORE ADDRESS OF NEXT DSCB 
MESSAGE AREA . . 100 BYTES 

2 . JFCB 176 BYTES 

3 . ECB . . ... 4 BYTES 
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*** 
*** 
*** 
*** 



DXLBL 

VOLLABI 

VOLNO 

VOLSERNO 

VOLSEC 

VOLVTOC 



VOLOWNER 



FL1LABI 

FL1NO 

FL1ID 

FL1FILSR 

FL1VOLSQ 

FL1FILSQ 

FL1GNO 

FL1VNG 

FL1CREDT 

FL1EXPDT 

FL1FSEC 

FL1BLKCT 

FL1SYSCD 

FL1RES 

FL1RES1 



FL2RECFM 

FL2BLKL 

FL2LRECL 

FL2DEN 

FL2FILP 

FL2JSID 

FL2JOBD 

FL2JSSP 

FL2STEPD 

FL2TRTCH 

FL2CNTRL 

FL2BLKA 
FL2RES 



SPACE 1 
SPACE 2 



SPACE 1 



SPACE 

DS 

DS 

DS 

DS 

DS 

DS 

DS 

DS 

DS 

DS 

DS 

DS 

SPACE 

SPACE 

ORG 

DS 

DS 

DS 

DS 

DS 

DS 

DS 

DS 

DS 

DS 

DC 

DS 

DS 

DS 

DS 

DS 

SPACE 

SPACE 

ORG 

DS 

DS 

DS 

DS 

DS 

DS 

DS 

DC 

DS 

DS 

DS 

DS 

DS 

DS 

SPACE 



1 

0CL8 

CL3 

CL1 

CL6 

CL1 

0CL10 

CL5 

CL5 

CLIO 

CLIO 

CLIO 

CL29 

1 

1 

DXLBL 

CL3 

CL1 

CL17 

CL6 

cm 

CL4 

CL4 

CL2 

CL6 

CL6 

C^' 

CL6 

CL13 

0CL7 

CL1 

CL6 

1 

1 

FL1ID 

CL1 

CL5 

CL5 

CL1 

CL1 

0CL17 

CL8 

cv 

CL8 

CL2 

CL1 

CL1 

CL1 

CL41 

1 



4 . IOB 40 BYTES 

5. DEB. 44 BYTES 

6. DCB 4 BYTES 

7. CCW S 96 BYTES 

TOTAL *** 464 BYTES 



VOLUME LABEL 



LABEL IDENTIFIER 
VOLUME LABEL NUMBER 



RESERVED 



RESERVED 

RESERVED 

OWNER NAME AND ADDRESS CODE 

RESERVED 




FILE LABEL 1 



LABEL IDENTIFIER 

FILE LABEL NUMBER 

FILE IDENTIFIER 

FILE SERIAL NUMBER 

VOLUME SEQUENCE NUMBER 

FILE SEQUENCE NUMBER 

GENERATION NUMBER 

VERSION NUMBER OF GENERATION 

CREATION DATE 

EXPIRATION DATE 

FILE SECURITY INDICATOR 

BLOCK COUNT 

SYSTEM CODE 

RESERVED FOR FUTURE USE 



FILE LABEL 2 



RECORD FORMAT 

BLOCK LENGTH 

BLOCKING FACTOR/RECORD LENGTH 

DENSITY 

FILE POSITION 

JOB/STEP IDENTIFICATION 

JOB IDENTIFICATION 

SLASH 

STEP IDENTIFICATION 

TAPE RECORDING TECHNIQUE 

CARRIAGE CONTROL CHARACTER 

RESERVED FOR FUTURE USE 

BLOCK ATTRIBUTE 

RESERVED FOR FUTURE USE 
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* 




DATA 




SPACE 


1 




ORG 


DXLBL 


DXDSCB 


DS 


0CL96 


DSCFMTID 


DC 


CI' 


DSCFILSR 


DS 


CL6 


DSCVOLSR 


DS 


CL2 


DSCCREDT 


DS 


CL3 


DSCEXPDT 


DS 


CL3 


DSCNOEXT 


DS 


CL1 


DSCBLDBL 


DS 


CL1 




DS 


CL1 


DSCSYSCD 


DS 


CL13 




DS 


CL7 


DSCFILTY 


DS 


CL2 


DSCRECFM 


DS 


CL1 


DSCOPTCD 


DS 


CL1 


DSCBLKL 


DS 


CL2 


DSCLRECL 


DS 


CL2 


DSCKEYL 


DS 


CL1 


DSCRKP 


DS 


CL2 


DSCDSIND 


DS 


CL1 


DSCSCALO 


DS 


CL4 


DSCLSTAR 


DS 


CL5 


DSCTRBAL 


DS 


CL2 


DSCEXTYP 


DS 


CL1 


DSCEXTSQ 


DS 


CL1 


DSCLOWLM 


DS 


CL4 


DSCUPPLM 


DS 


CL4 


DSCEXT1 


DS 


CLIO 


DSCEXT2 


DS 


CLIO 


DSCNEXT 


DS 


CL5 


DSCCORE 


DS 


CL4 


DSCBEND 


EQU 


* 




SPACE 


1 


* 




DATA 




SPACE 


1 




ORG 


DXDSCB 


DXDSCB 3K 


DS 


0CL4 


DSCBF3C 


DC 


X" 03 030303 • 


DSCBEXSK 


DS 


0CL4 


DSCBEXTY 


DS 


CL1 


DSCBEXSQ 


DS 


CL1 


DSCBLLMT 


DS 


CL4 


DSCBULMT 


DS 


CL4 


DSCBEX2 


DS 


CLIO 


DSCBEX3 


DS 


CLIO 


DSCBEX4 


DS 


CLIO 




SPACE 


1 


* 




DATA 




SPACE 


1 




ORG 


DXDSCB 


DSCBFMID 


DC 


C'3" 


DSCBEXSD 


DS 


0CL90 


DSCBEX5 


DS 


CLIO 


DSCBEX6 


DS 


CLIO 


DSCBEX7 


DS 


CLIO 


DSCBEX8 


DS 


CLIO 


DSCBEX9 


DS 


CLIO 


DSCBEXA 


DS 


CLIO 


DSCBEXB 


DS 


CLIO 


DSCBEXC 


DS 


CLIO 


DSCBEXD 


DS 


CLIO 


DSCBNEXT 


DS 


CL5 




SPACE 


1 



SET CONTROL BLOCK 



FILE SERIAL NUMBER 



CREATION DATE IN DISCONTINUOUS BIN 
EXPIRATION DATE IN DISCONTINUOUS BIN 



SYSTEM CODE 

FILE TYPE 
RECORD FORMAT 
OPTION CODE 
BLOCK LENGTH 
RECORD LENGTH 
KEY LENGTH 
KEY LOCATION 



EXTENT TYPE INDICATOR 
EXTENT SEQUENCE NUMBER 



POINTER TO NEXT RECORD 

CORE ADDRESS OF NEXT DSCB RECORD 



SET CONTROL BLOCK -FORMAT 3- KEY PORTION 



EXTENT TYPE INDICATOR 
EXTENT SEQUENCE NUMBER 
CCHH LOWER LIMIT 
CCHH UPPER LIMIT 
ADDITIONAL EXTENT 
ADDITIONAL EXTENT 
ADDITIONAL EXTENT 

SET CONTROL BLOCK -FORMAT 3- RECORD PORTION 



FORMAT ID 

ADDITIONAL EXTENTS 
ADDITIONAL EXTENT 
ADDITIONAL EXTENT 
ADDITIONAL EXTENT 
ADDITIONAL EXTENT 
ADDITIONAL EXTENT 
ADDITIONAL EXTENT 
ADDITIONAL EXTENT 
ADDITIONAL EXTENT 
ADDITIONAL EXTENT 
CCHHR OF NEXT FORMAT 3 DSCB 
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MESSAGE AREA 



SPACE 1 

ORG DXDSCB 



REPLYLTH 

REPLYADR 

REPLYECB 

MSGLSTSZ 

MCSFLAGS 

MESSAGEA 

DESCODE 

ROUTCODE 

REPLY 

* 

MSERL 
MINSTL 
MUNL 
MVOLL 

* MTXTL 

* MSGLTH 
* 

MSGIOSUP 
MSGSER 

MSGSERLO 

MSGINSTR 

MSGACTN 

MSGDN 

MSGVOLSR 

MSGTEXT 

DXJBF 



DXECB 



DXIOB 

IOBFLAG1 

IOBFLAG2 

IOBSENSE 

IOBSENSO 

IOBSENS1 

IOBECBPT 

IOBCSW 

IOBCOMAD 

IOBSTATO 

IOBSTAT1 

IOBCNT 

IOBSIOCC 



DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 

ORG 



EQU 
EQU 
EQU 
EQU 



DC 

DS 

ORG 

DS 

ORG 

DC 

ORG 

DS 

DC 

DC 

DC 

DC 

DC 

DS 

SPACE 



CL1 

CL3 

CL4 

CL2 

CL2 

CL68 

CL2 

CL2 

CL12 

MESSAGEA 



MSG LENGTH 
FLAG FIELD FOR MCS 
MESSAGE AREA 
DESCRIPTOR CODE FOR MCS 
ROUTING CODE FOR MCS 
REPLY AREA 



SPACE 

ORG 

DS 

IEFJFCBN 

SPACE 1 



DEFINITION OF LENGTH OF MESSAGE COMPONENTS 

3 MESSAGE SERIAL NUMBER LENGTH 

6 MSG INSTRUCTION LTH INC MSG SER 

3 MESSAGE UNIT NAME LENGTH 

6 MESSAGE VOLUME SERIAL LENGTH 

LENGTH MAY BE DEFINED BY EACH MODULE TO FIT REQUIREMENT 

LENGTH OF FULL MSG DEFINED BY EACH MODULE 

MESSAGE FORMAT IS •IEC000A M 000,00000 (TEXT) 

CLS'IEC" I/O SUPPORT MESSAGE IDENTITY 

0CL3 MESSAGE SERIAL NUMBER 

MSGSER+MSERL-1 

CL1 VOLUME SERIAL LO ORDER BYTE 

MSGSER 

CLS^OOOA M* MESSAGE INSTRUCTION INCL MSGSER 

MSGINSTR+MINSTL-1 

CL1 MESSAGE ACTION REQD BY OPERATOR 

C* • 

a^ooo* 

C* , * 

CL6 1 000000' 

C\' 

0CL3 8 

1 

JOB FILE CONTROL BLOCK 
1 

DSCBEND 
0CL176 




UNIT NAME THAT MSG REFERS TO 



VOLUME SERIAL THAT MSG REFERS TO 



EVENT CONTROL BLOCK 



SPACE 
DS 
DC 
SPACE 

SPACE 

DS 

DC 

DC 

DS 

DS 

DS 

DS 

DC 

DS 

DC 

DC 

DC 

DC 

DS 



1 

0CL4 

X 1 00000000 

1 



INPUT /OUTPUT BLOCK 



1 

0CL32 

X*00* 

X'00' 

OH 

CL1 

CL1 

XL1 

AL3( DXECB) 

0D 

X* 00000000 

X'OO' 

X* 00* 

X* 0000' 

XL1 



SENSE BYTE 1 



KEY, 0000, COMMAND ADDRESS 
STATUS BYTE 
STATUS BYTE 1 
COUNT 
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IOBSTART 


DC 


AL3 (DXCCW) 




IOBWGHT 


DS 


XL1 




IOBDCBPT 


DC 


AL3 (DXDCB) 






DS 


XL1 






DS 


XL3 




IOBINCAN 


DC 


X'OOOO* 




IOBERRCT 


DS 


XL2 




DXDAADDR 


DS 


D 


DIRECT ACCESS ADDRESS (MBBCCHHR) 




SPACE 


1 




* 




DATA 


EXTENT BLOCK 




SPACE 


1 




DYYYY 


DS 


0CL44 




DXDEB 


EQU 


DYYYY- 4 




DXDEBDEB 


DC 


X* 00000000* 




DXDEBOFL 


DS 


0CL1 




DXDEBIRB 


DC 


X* 00000000* 




DXDEBSYS 


DC 


X* 00000000* 




DXDEBUSR 


DC 


X* 00000000' 




DXDEBECB 


DC 


X* 00000000* 




DXDEBID 


DS 


0CL1 




DXDEBDCB 


DC 


ALU (DXDCB) 




DXDCBAD 


EQU 


DXDEBDCB 




DXDEBAPP 


DS 


CL4 




DXDEBMOD 


DS 


0CL1 




DXDEBUCB 


DS 


F 




DXDEBBIN 


DS 


H 




DXDEBSCC 


DS 


H 




DXDEBSHH 


DS 


H 




DXDEBECC 


DS 


H 




DXDEBEHH 


DS 


H 




DXDEBNTR 


DS 


H 






SPACE 


1 




* 




DATA 


CONTROL BLOCK 




SPACE 


1 




DXXXX 


DS 


OF 




DXDCB 


EQU 


DXXXX- 4 4 


POINTER TO RELATIVE BEGINNING OF : 


DXDCBDEB 


DC 


A (DXDEB) 






SPACE 


1 




* 




CHANNEL CONTROL WORDS 




SPACE 


1 






CNOP 


0,8 




DXCCW 


DS 


0CL96 




DXCCW1 


DS 


D 




DXCCW 2 


DS 


D 




DXCCW3 


DS 


D 




DXCCW4 


DS 


D 




DXCCW5 


DS 


D 




DXCCW6 


DS 


D 




DXCCW7 


DS 


D 




DXCCW8 


DS 


D 




DXCCW9 


DS 


D 




DXCCW10 


DS 


D 




DXCCWll 


DS 


D 




DXCCW12 


DS 


D 






SPACE 


1 




DSECTSIZ 


EQU 
MEND 


464 


CORE AREA REQUIRED FOR THIS MACRO 



DCB 
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IEFUCBOB Macro Instruction 

This macro instruction defines the symbolic names of all fields in the 
unit control block (UCB). Code this macro instruction with blank name 
and operand fields, and precede it with a DSECT statement. 

r t t 1 

j Name j Operation | Operand | 

j. + _ + ., 

| | IEFUCBOB | j 

L J JL J 



Control Statements Required 



//job name 

//stepname 

//SYSPRINT 

//SYSUT2 

//SYSIN 

./ ADD 



JOB {parameters} 

EXEC PGM=IEBUPDTE,PARM=NEW 

DD SYSOUT=A 

DD DSNAME=SYSl.MACLIB,DISP=OLD 

DD DATA 

NAME=IEFUCBOB , LIST=ALL 



IEFUCBOB Macro definition 



./ 
/* 



ENDUP 




IEFUCBOB Macro Definition 





MACRO 






IEFUCBOB 


UCBOB 


EQU * 






DS 


OF 


SRTEJBNR 


DS 


XL1 


UCBFL5 


DS 


XL1 


UCBID 


DS 


XL1 


SRTESTAT 


DS 


XL1 


SRTEONLI 


EQU 


12 8 


SRTECHGS 


EQU 


64 


SRTERESV 


EQU 


32 


SRTEUNLD 


EQU 


16 


SRTEALOC 


EQU 


8 


SRTEPRES 


EQU 


4 


SRTESYSR 
* 


EQU 


2 


SRTEDADI 
* 


EQU 


1 


* 

UCBCHA 


DS 


XL1 


UCBUA 


DS 


XL1 


UCBFL2 


DS 


XL1 


UCBDTI 


DS 


XL1 


UCBETI 


DS 


XL1 


UCBSTI 


DS 


XL1 


UCBLCI 


DS 


XL1 


UCBATI 


DS 


XL1 


UCBWGT 


DS 


XL1 



UNIT CONTROL BLOCKS 

JOB INTERNAL NUMBER 
EXPANDED SENSE INFORMATION 
UC3 IDENTIFICATION 
STATUS BITS 

ONLINE 

CHANGE ONLINE/OFFLINE 

RESERVED DEVICE 

UNLOAD THIS DEVICE 

BIT 4 ALLOCATED 

BIT 5 PERMANENTLY RESIDENT 

BIT 6 SYSRES, OR 

PRIMARY CONSOLE 

BIT 7 DADSM INTERLOCK, OR 

TAPE CONTAINS STANDARD LABELS, OR 
ALTERNATE CONSOLE 
FLAG1 AND CHANNEL ADDRESS 
UNIT ADDRESS 
FLAG2 

DEVICE TABLE 
ERROR TABLE 
STATUS TABLE 
LOGICAL CHANNEL TABLE 
ATTENTION TABLE 
WEIGHT 
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UCBNAME 


DS 


CL3 


UCBTYP 


DS 


XL4 


UCBTBYT1 


EQU 


UCBTYP 


UCB1FEA0 


EQU 


12 8 


UCB1FEA1 


EQU 


64 


UCB1FEA2 


EQU 


32 


UCB1FEA3 


EQU 


16 


UCB1FEA4 


EQU 


8 


UCB1FEA5 


EQU 


4 


UCB1FEA6 


EQU 


2 


UCB1FEA7 


EQU 


1 


UCBTBYT2 


EQU 


UCBTYP+1 


UCBTBYT3 


EQU 


UCBTYP+2 


UCB3TAPE 


EQU 


128 


UCB3COMM 


EQU 


64 


UCB3DACC 


EQU 


32 


UCB3DISP 


EQU 


16 


UCB3UREC 


EQU 


8 


UCB3CHAR 


EQU 


4 


UCBTBYT4 


EQU 


UCBTYP+3 


UCBLTS 


DS 


XL2 


UCBSNS 


DS 


0XL6 




DS 


XL2 


UCBNBRSN 


DS 


XL1 


UCBSNADR 


DS 


XL3 


SRTEVOLI 


DS 


0XL6 


UCBXTADR 


DS 


XL4 




DS 


XL2 


UCBUCSOl 


EQU 


12 8 


UCBUCS02 


EQU 


64 


SRTESTAB 


DS 


XL1 


SRTEBSVL 


EQU 


128 


SRTEBVSC 


EQU 


64 


SRTEBALB 


EQU 


32 


SRTEBPRV 


EQU 


16 


SRTEBPUB 


EQU 


8 


SRTEBVQS 


EQU 


4 


STREASCI 


EQU 


SRTEVBQS 


SRTEBJLB 


EQU 


2 


SRTEBNUL 


EQU 


1 


SRTEDMCT 


DS 


XL1 


SRTEFSCT 


DS 


XL2 


SRTEFSEQ 


DS 


XL2 


UCBSQC 


DS 


2F 


UCBSKA 


DS 


2F 


SRTEUSER 


DS 


XL1 


SRTEECBA 


DS 


XL3 



UNIT NAME IN 3 EBCDIC CHARACTERS 
DEVICE TYPE 

BYTE 1 OF UCBTYPE-MODEL 

BIT OF OPTION FIELD 

BIT 1 OF OPTION FIELD 

BIT 2 OF OPTION FIELD 

BIT 3 OF OPTION FIELD 

BIT 4 OF OPTION FIELD 

BIT 5 OF OPTION FIELD 

BIT 6 OF OPTION FIELD 

BIT 7 OF OPTION FIELD 
BYTE 2 OF UCBTYPE-OPTIONS 
BYTE 3 OF UCBTYPE- CLASS 

BIT OF CLASS - TAPE 

BIT 1 OF CLASS - COMMUNIC. 

BIT 2 OF CLASS - DIRECT AC 

BIT 3 OF CLASS - DISPLAY 

BIT 4 OF CLASS - UNIT REC. 

BIT 5 OF CLASS - CHAR. READ 
BYTE 4 OF UCBTYPE-DEVICE 
LAST 12* 
SENSE INFORMATION 

NUMBER OF SENSE BYTES 
ADDRESS OF SENSE INFORMATION 
VOLUME SERIAL 
ADDRESS OF UCB-UCS EXTENSION 

DEFAULT CHARACTER SET 
BUFFER LOADED in FOLD MODE 
STATUS B 

BIT SHARED VOLUME 

BIT 1 NOT USED 

BIT 2 ADD IT. VOL. LABEL PROC 

BIT 3 PRIVATE 

BIT 4 PUBLIC 

BIT 5 STORAGE FOR DIRECT 
ACCESS 

BIT 5 AMERICAN NATIONAL STANDARD LABEL 
FOR TAPE DATA SETS 

BIT 6 JOBLIB VOLUME 

BIT 7 CONTROL VOLUME 
DATA MANAGEMENT COUNT 
FILE SEQ. COUNT 
FILE SEQ. NUMBER 
SEEK QUEUE CONTROL WORD 
MBBCCHHR FOR LAST SEEK 
CURRENT NUMBER OF USERS 
DA ECB ADDRESS 



*THE FOLLOWING DESCRIBES ONE OF THE 10 SUB-UCBS FOR THE 2321 — 





ORG SRTEUSER 


DATACELL 


DS 0CL16 


DCELBBNR 


DS XL2 


DCELSTAB 


DS X 


DCELSTAT 


DS X 


DCELVOLI 


DS CL6 


DCELJBNR 


DS X 


DCELDMCT 


DS X 


DCELVTOC 


DS XL3 


DCELUSER 


DS X 


* PRINTER EXTENSION 


* 





10 OF THESE ARE PRESENT FOR 2321 

BIN NUMBER 

STATUS B 

STATUS A 

VOLUME SERIAL NUMBER 

INTERNAL JOB NUMBER 

DATA MANAGEMENT COUNT 

TTR OF VTOC START 

CURRENT NUMBER OF USERS 
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ORG 


UCBOB 




UCBUCSID 


DS 


CLU 


UCS IMAGE ID 


UCBUCSOP 


DS 


CL1 


UCS OPTIONS 


UCBFCBOP 


DS 


CL1 


FCB IMAGE OPTIONS 




DS 


CL2 


RESERVED BITS 


UCBFCBID 


DS 


CLU 


FCB IMAGE ID 


UCBERADR 


DS 


CL4 


ADDRESS ERP LOGOUT AREA 


* 3211 SENSE 


INFORMATION 






ORG 


UCBOB 




UCBSNSXT 


DS 


CL6 


3211 SENSE BYTES 




DS 


CL2 


RESERVED 



MEND 
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IEFJFCBN Macro Instruction 

This macro instruction defines the symbolic names of all fields in the 
job file control block (JFCB). Code this macro instruction with blank 
name and operand fields, and precede it with a DSECT statement. 



r t t 

j Name j Operation | Operand 
f 4 + 

| | IEFJFCBN | 

L I J. 



Control Statements Required 



// jobname 

//stepname 

//SYSPRINT 

//SYSUT2 

//SYSIN 

./ ADD 



./ 
/* 



JOB (parameters) 

EXEC PGM=IEBUPDTE , PARM=NEW 

DD SYSOUT=A 

DD DSNAME=SYS1.MACLIB,DISP=0LD 

DD DATA 

NAME=IEF JFCBN , LIST=ALL 



IEFJFCBN macro definition 



ENDUP 



IEFJFCBN Macro Definition 



INFMJFCB 
JFCBDSNM 
JFCBELNM 
JFCBTSDM 

JFCBSYSC 
JFCBDSCB 
JFCFCBID 
JFCAMPTR 
JFCRDBPT 
JFCBLTYP 

JFCBUFOF 
JFCBFLSQ 
JFCBVLSQ 
JFCBMASK 
JFCBCRDT 
JFCBXPDT 
JFCBIND1 
JFCBRLSE 
* 

JFCBLOCT 

JFCBNEWV 

JFCBPMEM 
* 

JFCBIND2 
JFCBSTAT 



MACRO 
IEFJFCBN 
EQU * 
DS CL44 
DS CL8 
DS CL1 



DS 
DS 
DS 
DS 
DS 
DS 

DS 
DS 
DS 
DS 
DS 
DS 
DS 
EQU 

EQU 

EQU 

EQU 

DS 
EQU 



0CL13 

CL3 

CL4 

CL3 

CL3 

CL1 

CL1 
CL2 
CL2 
CL8 
CL3 
CL3 
CL1 
64 

16 

4 
1 

CL1 

64 



DATA SET NAME 
ELEMENT NAME OR VERSION 
TASK SCHEDULER - DATA 
MANAGEMENT INTERFACE BYTE 
SYSTEM CODE 

FCB IMAGE ID 



LABEL TYPE AND USER'S-LABEL 

INDICATOR 

BUFFER OFFSET FOR TAPE DATA SETS 

FILE SEQUENCE NUMBER 

VOLUME SEQUENCE NUMBER 

DATA MANAGEMENT MASK 

DATA SET CREATION DATE 

DATA SET EXPIRATION DATE 

INDICATOR BYTE 1 
BITS AND 1 - EXTERNAL 
STORAGE RELEASE INDICATOR 
BITS 2 AND 3 - DATA SET 
HAS BEEN LOCATED 
BITS 4 AND 5 - NEW VOLUME 
ADDED TO DATA SET 
BITS 6 AND 7 - DATA SET IS 
A MEMBER OF A PODS OR GDG 

INDICATOR BYTE 2 
BITS AND 1 - DATA SET 
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JFCBSCTY 
* 


EQU 


16 


JFCBUFNO 


DS 


0AL1 


JFCBUFRQ 


DS 


AL1 


JFCBFTEK 


DS 


0BL1 


JFCBFALN 


DS 


BL1 


JFCBUFL 


DS 


AL2 


JFCEROPT 


DS 


BL1 


JFCTRTCH 


DS 


0BL1 


JFCKEYLE 


DS 


0AL1 


JFCMODE 


DS 


0BL1 


JFCCODE 


DS 


0BL1 


JFCSTACK 


DS 


0BL1 


JFCPRTSP 


DS 


BL1 


JFCDEN 


DS 


BL1 


JFCLIMCT 


DS 


AL3 


JFCDSORG 


DS 


BL2 


JFCRECFM 


DS 


BL1 


JFCOPTCD 


DS 


BL1 


JFCBLKSI 


DS 


AL2 


JFCLRECL 


DS 


AL2 


JFCNCP 


DS 


AL1 


JFCNTM 


DS 


AL1 


JFCUCSID 


DS 


0CL4 


JFCRKP 


DS 


AL2 


JFCCYLOF 


DS 


AL1 


JFCDBUFN 


DS 


AL1 


JFCUCSOP 


DS 


0CL1 


JFCINTVL 


DS 


AL1 


JFCCPRI 


DS 


BL1 


JFCSOWA 


DS 


AL2 


JFCBNTCS 


DS 


CL1 


JFCBNVOL 


DS 


CL1 


JFCBVOLS 


DS 


CL3 


JFCBEXTL 
* 


DS 


CL1 


* 

JFCBEXAD 


DS 


CL3 


JFCBPQTY 


DS 


CL3 


JFCBCTRI 


DS 


CL1 


JFCBSQTY 


DS 


CL3 


JFCBIND3 


DS 


CL1 


JFCBCNTG 


EQU 


64 


JFCBMXIG 


EQU 


16 


JFCBALXI 


EQU 


4 


JFCBRNDC 


EQU 


1 


JFCBDQTY 
* 


DS 


CL3 


JFCBSPNM 


DS 


CL3 


JFCBABST 


DS 


CL2 


JFCBSBNM 

* 

JFCBDRLH 


DS 


CL3 


DS 


CL3 


JFCBVLCT 


DS 


CL1 


JFCBSPTN 


DS 


CL1 


JFCBLGTH 


EQU 


176 


JFCBEND 


EQU 

MEND 


* 



STATUS (NEW, OLD, OR MOD) 
BITS 2 AND 3 - DATA SET 
SECURITY INDICATOR 




UCS ID 



UCS OPTIONS 



NUMBER OF OVERFLOW TRACKS 
NUMBER OF VOLUME SERIAL NUMBERS 
VOLUME SERIAL NUMBERS (THE FIRST FIVE) 
LENGTH OF BLOCK OF EXTRA 
VOLUME SERIAL NUMBERS 
(BEYOND FIVE) 

TRACK ADDRESS OF BLOCK OF 
EXTRA VOLUME SERIAL NUMBERS 

PRIMARY QUANTITY OF D.A. STORAGE REQUIRED 
INDICATES WHETHER CYLINDERS, TRACKS, OR RECORDS 
ARE SPECIFIED IN JFCBPQTY AND JFCBSQTY 
SECONDARY QUANTITY OF D.A. STORAGE REQUIRED 
INDICATOR BYTE 3 

BITS AND 1 - CONTIGUOUS STORAGE INDICATOR 
BITS 2 AND 3 - MAXIMUM 
AVAILABLE EXTENT INDICATOR 
BITS 4 AND 5 - ALL EXTENTS INDICATOR 
BITS 6 AND 7 - ROUND CYLINDER INDICATOR 
QUANTITY OF D.A. STORAGE 
REQUIRED FOR A DIRECTORY 
CORE ADDRESS OF THE JFCB 
WITH WHICH CYLINDERS ARE SPLIT 
RELATIVE ADDRESS OF FIRST 
TRACK TO BE ALLOCATED 
CORE ADDRESS OF THE JFCB 

FROM WHICH SPACE IS TO BE SUBALLOCATED 
AVERAGE DATA RECORD LENGTH 
VOLUME COUNT 

NUMBER OF TRACKS PER CYLINDER TO BE USED BY 
THIS DATA SET WHEN SPLIT CYLINDERS IS INDICATED 
LENGTH OF JFCB 
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Execute Channel Program (EXCP) 
Macro Instruction 



This chapter contains a general description 
of the function and application of the 
execute channel program (EXCP) macro 
instruction, accompanied by descriptions of 
specific control blocks and macro 
instructions used with EXCP. Factors that 
affect the operation of EXCP, such as 
device variations and program modification, 
are also discussed. 

The EXCP macro instruction provides you 
with a device-dependent means of performing 
the I/O operations. Before reading this 
chapter, you should be familiar with system 
functions and with the structure of control 
blocks, as well as with the operational 
characteristics of the I/O devices required 
by your channel programs. Operational 
characteristics of specific I/O devices are 
contained in IBM System Reference Library 
publications for each device. 



PREREQUISITE PUBLICATIONS 

The IBM System/360 Operating System; 
| Supervisor Services and Macro Instructions 
publication (GC28-6646) explains the 
standard procedures for I/O processing 
under the operating system. 

The IBM System/360 Operating System: 
Assembler Language publication (GC28-6514) 
contains the information necessary to code 
programs in the assembler language. 

I The IBM System/360 Operating System; 
Data Management Macro Instructions 
publication (GC26-3794) describes the 
system macro instructions that can be used 
in programs coded in the assembler 
language. 

The IBM System/360 Operating System: 
System Control Blocks publication 
(GC28-6628) contains format and field 
descriptions of the system control blocks 
referred to in this chapter. 
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Execute Channel Program (EXCP) Macro Instruction 

Execute channel program (EXCP) is a macro instruction of System/360 
Operating System that causes a supervisor-call interruption to pass 
control to the input/output supervisor. EXCP also provides the 
input/output supervisor with control information regarding a channel 
program to be executed. When the IBM standard data access methods are 
being used, the access method routines are responsible for issuing EXCP. 
If you are not using the standard access methods, you may issue EXCP 
directly. Direct use of EXCP provides you with device dependence in 
organizing data and controlling I/O devices. 

You issue EXCP primarily for I/O programming situations to which the 
standard access methods do not apply. When you are writing your own 
data access methods, you must include EXCP for I/O operations. EXCP 
must also be used for processing of nonstandard labels, including the 
reading and writing of labels and the positioning of magnetic tape 
volumes . 

To issue EXCP, you must provide a channel program (a list of channel 
command words) and several control blocks in your program area. The 
input/output supervisor then schedules I/O requests for the device you 
have specified, executes the specified I/O commands, handles I/O 
interruptions, directs error recovery procedures, and posts the results 
of the I/O requests. 

When planning EXCP operations and appendages for use on central 
processing units with parallel processing, special precautions must be 
observed. Examples of such central processing units are the IBM 
| System/ 360 Models 91 and 195 and the IBM System/370 Model 195 that can 
execute instructions in a sequence other than the physical sequence in 
which they appear in a listing. Such a central processing unit 
maintains logical consistency in its own operations, including the 
beginning and ending of I/O operations. However, it is impossible for 
such a central processing unit to maintain consistency with operations 
performed by asynchronous units. This type of central processing unit 
recognizes a special "no operation" to force sequential operations in 
the environments where it might be required. The appropriate hardware 
manual should be carefully studied before coding EXCP and appendage 
routines for this type of central processing unit. 

Refer to the topic "Block Multiplexer Channel Programming Notes" for 
special conditions encountered with command retry. 



Use of EXCP In System and Problem Programs 

This section briefly explains the procedures performed by the system and 
the programmer when the EXCP macro instruction is issued by the routines 
of the standard data access methods. The additional procedures that you 
must perform when issuing the EXCP macro instruction yourself are then 
described by direct comparison. 
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SYSTEM USE OF EXCP 

When using a standard data access method to perform I/O operations, the 
programmer is relieved of coding channel programs, and of constructing 
the control blocks necessary for the execution of channel programs. To 
permit I/O operations to be handled by an access method, the programmer 
need only issue the following macro instructions: 

• A DCB macro instruction that produces a data control block (DCB) for 
the data set to be retrieved or stored. If appendages are not being 
used, a short DCB is constructed. Such a DCB does not support 
reduced error recovery. 

• An OPEN macro instruction that initializes the data control block 
and produces a data extent block (DEB) for the data set. 

• A macro instruction (e.g., GET, WRITE) that requests I/O operations. 

Access method routines will then: 

1. Create a channel program that contains channel commands for the I/O 
operations on the appropriate device. 

2. Construct an input/output block (IOB) that contains information 
about the channel program. 

3. Construct an event control block (ECB) that is later supplied with 
a completion code each time the channel program terminates. 

4. Issue an EXCP macro instruction to pass the address of the IOB to 
the routines that initiate and supervise the I/O operations. 

The input/output supervisor will then: 

5. Schedule the I/O request. 

6. Issue a start input/output (SIO) instruction to activate the I/O 
device. 

7. Process I/O interruptions and schedule error recovery procedures, 
when necessary. 

8. Place a completion code in the event control block after the 
channel program has been executed. 

The programmer is not concerned with these procedures and does not 
know the status of I/O operations until they are completed. 
Device-dependent operations are limited to those provided by the macro 
instructions of the particular access method selected. 

PROGRAMMER USE OF EXCP 

If you wish to issue the EXCP macro instruction directly, you must 
perform the procedures that the access methods perform, as summarized in 
items 1 through 4 of the preceding discussion. You must, in addition to 
constructing and opening the data control block with the DCB and OPEN 
macro instructions, construct a channel program, an input/output block, 
and an event control block before you can issue the EXCP macro 
instruction. The input/output supervisor always handles items 5 through 
8. 

After issuing the EXCP macro instruction, you should issue a WAIT 
macro instruction specifying the event control block to determine 
whether the channel program has terminated. If volume switching is 
necessary, you must issue an EOV macro instruction. When processing of 
the data set has been completed, you must issue a CLOSE macro 
instruction to restore the data control block. 



Execute Channel Program (EXCP) Macro Instruction 49 




EXCP Requirements 

This section describes the channel program that you must provide in 
order to issue the EXCP macro instruction- The control blocks that you 
must either construct directly, or cause to be constructed by use of 
macro instructions, are also described. 

CHANNEL PROGRAM 

The channel program supplied by you and executed through EXCP is 
composed of channel command words (CCWs) on doubleword boundaries. Each 
channel command word specifies a command to be executed and, for 
commands initiating data transfer, the area to or from which the data is 
to be transferred. Channel command word formats used with specific I/O 
devices can be found in IBM Systems Reference Library publications for 
each device. All channel command words described in these publications 
can be used, with the exception of REWIND and UNLOAD (RUN) . 

Data and Command Chaining 

Chaining is the successive loading of channel command words into a 
channel from contiguous doubleword locations in main storage. Data 
chaining occurs when a new channel command word loaded into the channel 
defines a new storage area for the original I/O operation. Command 
chaining occurs when the new channel command word specifies a new I/O 
operation. For detailed information about chaining, refer to the IBM 
System/ 360: Principles of Operation publication (GA22-6821) . 

To specify either data chaining or command chaining, you must set 
appropriate bits in the channel command word, and indicate the type of 
chaining in the input/output block. Both data and command chaining 
should not be specified in the same channel command word; if they are, 
data chaining takes precedence. 

When a channel program includes a list of channel command words that 
chain data for reading operations, no channel command word may alter the 
contents of another channel command word in the same list. (If such 
alteration were allowed, specifications could be placed into a channel 
command word without being checked for validity. If the specifications 
were incorrect, the error could not be detected until the chain was 
completed. Data could be read into incorrect locations and the system 
could not correct the error. ) 

CONTROL BLOCKS 

When using the EXCP macro instruction, you must be familiar with the 
function and structure of an input/output block (IOB) , an event control 
block (ECB), a data control block (DCB) , and a data extent block (DEB). 
Brief descriptions of these control blocks follow. Their fields are 
illustrated in the section "EXCP Programming Specifications." 

Input/Output Block (IOB) 

The input/output block is used for communication between the problem 
program and the system. It provides the addresses of other control 
blocks, and maintains information about the channel program, such as the 
type of chaining and the progress of I/O operations. You must define 
the input/output block and specify its address as the only parameter of 
the EXCP macro instruction. 
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Event Control Block (ECB) 

The event control block provides you with a completion code that 
describes whether the channel program was completed with or without 
error- A WAIT macro instruction for synchronizing I/O operations with 
the problem program must be directed to the event control block. You 
must define the event control block and specify its address in the 
input/output block. 

Data Control Block (DCB) 



The data control block provides the system with information about the 
characteristics and processing requirements of a data set to be read or 
written by the channel program. A data control block must be produced 
by a DCB macro instruction that includes parameters for EXCP. If 
appendages are not being used, a short DCB is constructed. Such a DCB 
does not support reduced error recovery. You specify the address of the 
data control block in the input/output block. 

Data Extent Block (DEB) 



The data extent block contains one or more extent entries for the 
associated data set, as well as other control information. An extent 
defines all or part of the physical boundaries on an I/O device occupied 
by, or reserved for, a particular data set. Each extent entry contains 
the address of a unit control block (UCB) , which provides information 
about the type and location of an I/O device. More than one extent 
entry can contain the same UCB address. (Unit control blocks are set up 
at system generation time and need not concern you.) For all I/O 
devices supported by the operating system, the data extent block is 
produced during execution of the OPEN macro instruction for the data 
control block. The system places the address of the data extent block 
into the data control block. (Opening an EXCP data set with DSORG=IS 
will not produce an ISAM section in the DEB. ) 



Channel Program Execution 

This section explains how the system uses your channel program and 
control blocks after the EXCP macro instruction has been issued. 

INITIATION OF CHANNEL PROGRAM 

By issuing the EXCP macro instruction, you request the execution of the 
channel program specified in the input/output block. The input/output 
supervisor checks the request for validity by ensuring that the required 
control blocks contain the correct information. If they do not, 
abnormal termination procedures are initiated. A program check occurs 
if the control blocks are not on correct boundaries. 

The input /output supervisor obtains the address of the data control 
block from the input/output block and the address of the data extent 
block from the data control block. From the data extent block, the 
system obtains the address of the unit control block (UCB) for the 
desired I/O device. To protect and facilitate reference to the 
addresses of the IOB, DEB, and UCB, the input/output supervisor places 
these addresses, along with other information about the channel program, 
into an area called a request element. The request element is used by 
the input/output supervisor for forming queues to keep track of I/O 
requests. A channel program's request element is "available" if the 
information it contains is no longer to be used by the input/output 
supervisor and if it is ready to receive information about another 
request. When a request element is "made available", it is removed from 
all request queues and placed on a queue of available request elements. 
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You are not concerned with the contents of the request element unless 
you have provided appendage routines, as explained in the section 
"Appendages . " 

After completing the request element for the channel program, the 
input/output supervisor determines whether a channel and the requested 
I/O device are ready for the channel program. If they are not ready, 
the request element is placed into the appropriate queue, and control is 
returned to the problem program. The channel program is subsequently 
executed when the channel and device are ready. 

To initiate execution of the channel program, the system obtains its 
address from the input/output block, places this address into the 
channel address word (CAW) , and issues a start input/ output (SIO) 
instruction. 

Before issuing the SIO instruction for direct access devices, the 
system issues the initial seek, which is overlapped with other 
operations. You specify the seek address in the input/ output block. 
When the seek has completed, the system constructs a command chain to 
reissue the seek, set the file mask specified in the data extent block, 
and pass control to your channel program. (When using the operating 
system, you cannot issue the initial seek or set the file mask yourself. 
The file mask is set to prohibit seek Cylinder commands, or, if space is 
allocated by tracks, Seek Track commands. If the data set is opened for 
INPUT or RDBACK, Write commands are also prohibited.) 

Before issuing SIO for magnetic tape devices, the system constructs a 
command chain to set the mode specified in the data extent block and 
pass control to your channel program. (When using the operating system, 
you cannot set the mode yourself.) 

COMPLETION OF CHANNEL PROGRAM 

The system considers the channel program completed when it receives an 
indication of a channel end condition. When channel end occurs, the 
request element for the channel program is made available, and a 
completion code is placed into the event control block. The completion 
code indicates whether errors are associated with channel end. If 
device end occurs simultaneously with channel end, errors associated 
with device end (i.e., unit exception or unit check) are also accounted 
for. 

Device End Errors 

If device end occurs after channel end and an error is associated with 
device end, the completion code in the event control block does not 
indicate the error. However, the status of the unit and channel is 
saved in the unit control block (UCB) for the device, and the UCB is 
marked as intercepted. The input/output block for the next request 
directed to the I/O device is also marked as intercepted. The error is 
assumed to be permanent, and the completion code in the event control 
block for the intercepted request indicates interception. The IFLGS 
field of the data control block is also flagged to indicate a permanent 
error. It should be noted that when a Write Tape Mark or Erase Long Gap 
CCW is the last (or only) CCW in your channel program, the I/O 
supervisor will not attempt recovery procedures for device end errors. 
In these circumstances, command chaining a NOPCCW to your Write Tape 
Mark or Erase Long Gap CCW ensures initiation of device end error 
recovery procedures. 

To be prepared for device end errors, you should be familiar with 
device characteristics that can cause such errors- After one of your 
channel programs has terminated, you should not release buffer space 

52 Data Management for System Programmers 



until you have determined that your next request for the device has not 
been intercepted. You may reissue an intercepted request. 



INTERRUPTION HANDLING AND ERROR RECOVERY PROCEDURES 

An I/O interruption allows the CPU to respond to signals from an I/O 
device which indicate either termination of a phase of I/O operations or 
external action on the device. A complete explanation of I/O 
interruptions is contained in the IBM System/360: Principles of 
Operation publication. For descriptions of interruptions by specific 
devices, refer to IBM Systems Reference Library publications for each 
device. 

If error conditions are associated with an interruption, the 
input/output supervisor schedules the appropriate device-dependent error 
routine. The channel is then restarted with another request that is not 
related 1 to the channel program in error. If the error recovery 
procedures fail to correct the error, the system places ones in the 
first two bit positions of the IFLGS field of the data control block. 
You are informed of the error by an error code that the system places 
into the event control block. 

Error Recovery Procedures for Related Channel Programs 

Related channel programs are requests that are associated with a 
particular data control block and data extent block in the same job 
step. They must be executed in a definite order, i.e., the order in 
which the requests are received by the input/output supervisor. A 
channel program is not started until all previous requests for related 
channel programs have been completed. You specify, in the input/output 
block, whether the channel program is related to others. 

If a permanent error occurs in a channel program that is related to 
other requests, the request elements for all the related channel 
programs are removed from their queue and made available. This process 
is called purging. The addresses of the input/output blocks for the 
related channel programs are chained together, with the address of the 
first input/output block in the chain placed into the "User Purge IOB 
Address" field of the data extent block. The address of the second 
input/ output block is placed into the "Restart Address" field of the 
first input/ output block, and so on. The last input/ out put block in the 
chain is indicated by all ones in its Restart Address field. The chain 
defines the order in which the request elements for the related channel 
programs are removed from the request queue. 

For all requests that are related to the channel program in error, 
the system places completion codes into the event control blocks. The 
IFLGS field of the data control block is also flagged. Any requests for 
a data control block with error flags are posted complete without 
execution. If you wish to reissue requests that are related to the 
channel program in error, you must reset the first two bits of the IFLGS 
field of the data control block to zeros. You then issue a RESTORE 
macro instruction, specifying, as the only parameter, the address of the 
"User Purge IOB Address" field of the data extent block. This causes 
execution of all the related channel programs. (The RESTORE macro 
definition and how to add it to the macro- library are in the Appendix of 
this chapter.) Alternatively, if you wish to restart only particular 
channel programs rather than all of them, you may reissue the EXCP macro 
instruction for each channel program desired. 




^Related channel programs are discussed in the next section. 
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Appendages 

This section discusses the appendages that you may optionally code when 
using the EXCP macro instruction. Before a programmer- written appendage 
can be executed, it must be included in the SVC library. These 
procedures are explained first; descriptions of the routines themselves 
and of their coding specifications follow. 

DEFINING APPENDAGES 

An appendage must be defined in a DD statement as a member of a SYS1 
partitioned data set. The full member name of an appendage is eight 
bytes in length, but the first six bytes are required by IBM standards 
to be the characters IGG019. The last two characters must be provided 
by you as an identification; they may range in collating sequence from 
WA to Z9. 

ENTERING APPENDAGES INTO SVC LIBRARY 

The SVC library is a partitioned data set named SYS1.SVCLIB. You can 
insert an appendage into the SVC library during the system generation 
process or by link-editing it into the SYS1.SVCLIB. The routine must be 
a member of a cataloged partitioned data set whose name begins with 
SYS1. 

To enter a routine into the SVC library during system generation, you 
use the SVCLIB macro instruction. The format of this macro instruction 
is given in the publication IBM System/360 Operating System: System 
Generation, GC28-6554. 



CHARACTERISTICS OF APPENDAGES 

An appendage is a programmer- written routine that provides additional 
control over I/O operations during channel program execution. By 
providing appendages, you can examine the status of I/O operations and 
determine the actions to be taken for various conditions. An appendage 
may receive control when one of the following occurs: 

• Start I/O is issued. 

• Program controlled interruption. 

• End of extent. 

• Channel end. 

• Abnormal end. 

Appendages are executed in supervisor state. You must not issue, in 
an appendage, any SVC instructions or instructions that change the 
status of the computing or operating system (e.g., WTO, LPSW, SVC, or 
any privileged instruction). Since appendages are disabled for all 
types of interruptions except machine checks, you also must not enter 
loops that test for completion of I/O operations. An appendage must not 
alter storage used by either the supervisor or the input/output 
supervisor. 
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The identification of an appendage, which consists of the last two 
characters of its 8-character name, must be specified in the DCB macro 
instruction, as described in the section "EXCP Programming 
Specifications." When the OPEN macro instruction for the data control 
block is issued, any appendages specified in the DCB macro instruction 
are loaded into main storage. The appendages are linked to the 
input/ output supervisor when their addresses are placed into a table of 
addresses called an appendage vector table. This table is always 
constructed by the system when OPEN is issued; if an appendage is not 
provided, the table contains the address of a return branch instruction 
to the input/output supervisor. Using the appendage vector table, the 
input/output supervisor branches and links to an appendage at the 
appropriate time. The address of the starting location of the appendage 
is placed into register 15. 

Parameters are passed to appendages by the input/output supervisor. 
These parameters are contained in registers, and are as follows: 

• Register 1 ; Address of the request queue element (RQE) for the 
channel program. 

The request queue element contains the following information: 

Bytes 1 and 2 - 

Link field when the RQE is an I/O queue. 
Bytes 3 and 4 - 

Address of the unit control block (UCB) for the I/O device. 
Byte 5 - 

Identification of the task control block (TCB) for the task. 

(In a multitasking environment, this field is not used. It 

contains all zeros if the request element is not available and 

all ones when the request element is available.) 
Bytes 6, 7, and 8 - 

Address of the input/output block. 
Byte 9 - 

Priority of the request, if the priority option has been 

selected for the system. 
Bytes 10, 11, and 12 - 

Address of the data extent block. 

The request queue element is normally 12 bytes in length; for a 
multitasking environment, it includes 4 more bytes that contain the 
address of the TCB. 

• Register 2 




• Register 3 



• Register 4 



• Register 7 



Address of the input/output block (IOB) . 
Address of the data extent block (DEB). 
Address of the data control block (DCB). 
Address of the unit control block (UCB) . 

• Register 14 : Address of the location in the input/ out put supervisor 

to which control io to be returned after execution of 
the appendage. When passing control from an appendage 
to the system, you may use displacements to the return 
address in register 14 for optional return procedures. 
Some of these procedures differ in their treatment of 
the request element associated with the channel 
program. 

• Register 15 : Address of the entry point to the appendage. 

You may not change register 1 in an appendage; this is reserved in 
case an abnormal condition occurs while the appendage is in control. 
Register 9, if used, must be set to binary zero before control is 
returned to the system. All other registers, except those indicated in 
the descriptions of each appendage, must be saved and restored if they 
are used. The following table summarizes register conventions. 
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r T T T : 1 

| Appendages | Entry Point | Returns | Available Work Reg. | 
j. + + T + j 

| Extent Error j 
Reg 14+0 | Return j 

Reg 14 + 4 jskip j Reg. 10, 11, 12 S 13 
Reg 14+8 |Try Again j 

Reg 14+0 | Normal | Reg. 10, 11 S 13 
Reg 14+4 jskip j 

Reg 14+0 | Normal | Reg. 10, 11, 12 S 13 



EOE 



SIO 



PCI 



j Reg 15 

I 

I 

+ 

j Reg 15 

I 

| Reg 15 



CE 



XCE 



j Reg 15 

I 

I 

I 

| Reg 15 



Reg 14 
Reg 14 
Reg 14 
Reg 14 

Reg 14 
Reg 14 
Reg 14 
Reg 14 



+ j Normal 
+ 4 jskip 
+ 8 |Re-EXCP 
+ 12 | By-Pass 

+ j Normal 
+ 4 jskip 
+ 8 JRe-EXCP 
+ 12 j By-Pass 



| Reg. 10, 11, 12 S 13 



Reg. 10, 11, 12 S 13 



The types of appendages are listed in the following paragraphs, with 
explanations of when they are entered, how they return control to the 
system, and which registers they may use without saving and restoring. 

Start Input/Output (SIO) Appendage 

This appendage is entered before the input/output supervisor issues a 
start input/output (SIO) instruction unless an error recovery procedure 
is in control. If SIO is not initiated because of a busy condition, the 
appendage will be reentered before SIO is reissued. 

If the return address in register 14 is used to return control to the 
input/output supervisor, the I/O operation is executed normally. You 
may optionally bypass the SIO instruction and prevent execution of the 
channel program by using the contents of register 14 plus 4 as the 
return address. In this case, the channel program is not posted 
complete, but its request element is made available. You may do the 
posting by taking the following steps: 

1. Save necessary registers. 

2. Place pointer to post entry address from the CVT in Reg 15. 

3. Place current TCB address from the CVT in Reg 12. 

4. Place ECB address from the IOB in Reg 11. 

5. Set the completion code in the high order byte in Reg 10. 

6. Go to Post using BALR 14, 15. 

You may use registers 10, 11, and 13 in a start input /out put 
appendage without saving and restoring their contents. 
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Program Controlled Interruption (PCI) Appendage 

This appendage is entered when a program controlled interruption occurs. 
At the time of the interruption, the contents of the channel status word 
will not have been placed in the * channel status word" field of the 
input/output block. The channel status word can be obtained from 
location 64. You must use the return address in register 14 to allow 
the system to proceed with normal interruption processing. 

You may use registers 10 through 13 in a program controlled 
interruption appendage without saving and restoring their contents. 
This appendage may be reentered for the same channel program if the 
error recovery procedure is in the process of retrying a CCW with the 
program controlled bit set on. The IOBERR flag is set when the error 
recovery procedure is in control (IOBFL1 = X'20'). 

Refer to the topic "Block Multiplexer Channel Programming Notes" for 
special PCI conditions encountered with command retry. 



End-of -Extent Appendage 

This appendage is entered when the seek address specified in the 
input/ output block is outside the allocated extent limits indicated in 
the data extent block. 

If you use the return address in register 14 to return control to the 
system, the abnormal end appendage is entered. An end-of -extent error 
code (X'42*) is placed in the "ECB code" field of the input/ output block 
for subsequent posting in the event control block. 

You may use the following optional return addresses: 

• Contents of register 14 plus 4 - The channel program is posted 
complete; its request element is returned to the available queue. 

• Contents of register 14 plus 8 - The request is tried again. 

You may use registers 10 through 13 in an end-of -extent appendage 
without saving and restoring their contents. 

Note : If an end-of -cylinder or file-protect condition occurs, the 
input/ output supervisor updates the seek address to the next higher 
cylinder or track address, and re-executes the request. If the new seek 
address is within the data set's extent, the request is executed; if the 
new seek address is not within the data set's extent, the end-of-extent 
appendage is entered. If you wish to try the request in the next 
extent, you must move the new seek address into the UCB at UCB+48. 

If a file protect condition occurs and was caused by a full seek 
(command code=07) embedded within a channel program, the request is 
flagged as a permanent error, and the abnormal end appendage is entered. 

Channel End Appendage 

This appendage is entered when a channel end, unit exception with or 
without channel end, or channel end with wrong length record occurs 
without any other abnormal end conditions. 
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If you use the return address in register 14 to return control to the 
system, the channel program is posted complete, and its request element 
is made available. In the case of unit exception or wrong length 
record, the error recovery procedure is performed before the channel 
program is posted complete, and the IOBEX flag (X* 04*) in IOBFL1 is set 
on- The condition code may be directly tested by using a BC 
instruction. A CC=0 means no UEX or WLR accompanied this interruption. 
The CSW status may be obtained from the IOBCSW. 

If the appendage takes care of the wrong length record and/or unit 
exception it may turn off the IOBEX (x'OU'" ) flag in IOBFL1 and return 
normally. The event will then be posted complete (completion code 7F 
under normal conditions, taken from the high-order byte of the IOBECB 
field). If the appendage returns normally without resetting the IOBEX 
flag to zero, the request will be routed to the associated device error 
routine, and then the abnormal end appendage will be immediately 
entered. This abnormal end appendage will be entered with IOBECB 
completion code = *41'. 

You may use the following optional return addresses: 

• Contents of register 14 plus 4 - The channel program is not posted 
complete, but its request element is made available. You may post 
the event by using the calling sequence described under the start 
I/O appendage. This is especially useful if you wish to post an ECB 
other than the IOBECB. 

• Contents of register 14 plus 8 - The channel program is not posted 
complete, and its request element is placed back on the request 
queue so that the I/O operation can be retried. For correct 
re-execution of the channel program, you must re-initialize the 
"Flags 1", "Flags 2", and "Flags 3" fields of the input/output block 
and set the "Error Counts" field to zero. As an added precaution, 
the IOBSNS and IOBCSW fields should be cleared. 

• Contents of register 14 plus 12 - The channel program is not posted 
complete, and its request element is not made available. (The 
request element is assumed to be used in a subsequent asynchronous 
exit routine.) 

You may use registers 10 through 13 in a channel end appendage 
without saving and restoring their contents. 



Abnormal End Appendage 

This appendage may be entered on abnormal conditions, such as: unit 
check, unit exception, wrong length indication, program check, 
protection check, channel data check, channel control check, interface 
control check, chaining check, out-of-extent error, and intercept 
condition (i.e., device end error). It may also be entered when an EXCP 
is issued for a DCB that has already been purged. 

1. When this appendage is entered due to a unit exception and/or wrong 
length record indication, the IOBECB code is set to X'41*. For 
further information on these conditions see "Channel End 
Appendage . " 

2. When the appendage is entered due to an out-of-extent error, the 
IOBECB code is set to X , 42 f . 
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3. When the appendage is first entered due to an intercept condition, 
the IOBECB code is set to X'TE*. If it is then determined that the 
error condition is permanent, the appendage will be entered a 
second time with the IOBECB code set to X*44'. The intercept 
condition signals that an error was detected at device end after 
channel end on the previous request. 

4. When the appendage is entered due to an EXCP being issued to an 
already purged DCB, this request will enter the abnormal end 
appendage with the IOBECB code set to X'48". This applies only to 
related requests. 

5. When the appendage is entered with the IOBECB code set to 7F r it 
may be due to a unit check, program check, protection check, 
channel data check, channel control check, interface control check 
or chaining check. When the IOBECB code is 7F, it may be the first 
detection of an error in the associated channel program, or it 
could occur after an error routine has attempted to correct the 
error but was unsuccessful in its retry. Under these two 
conditions, the IOBERR flag is set; it indicates that the error 
routine is in control but has not yet declared the error to be 
permanent. 

To determine if an error is permanent, you should check the "ECB 
code" field of the input/output block. To determine the type of error, 
check the channel status word and the sense information in the IOB. 
However, when the ECB code is X'42" or X'48' # these fields are not 
applicable. For X'44* the CSW is applicable, but the sense is valid 
only if the unit check bit is set. If you use the return address in 
register 14 to return control to the system, the channel program is 
posted complete, and its request element is made available. (The 
SYNADAF macro instruction described in the Supervisor and Data 
Management Macro Instructions publication may be used in an error 
analysis routine to analyze permanent I/O errors.) You may use the 
following optional return addresses: 

• Contents of register 14 plus 4 - The channel program is not posted 
complete, but its request element is made available. 

• Contents of register 14 plus 8 - The channel program is not posted 
complete, and its request element is placed back on the request 
queue so that the request can be retried. For correct re-execution 
of the channel program, you must re- initialize the "Flags 1", "Flags 
2", and "Flags 3" fields of the input/output block and set the 
"Error Counts" field to zero. As an added precaution, the IOBSNS 
and IOBCSW fields should be cleared. 

• Contents of register 14 plus 12 - The channel program is not posted 
complete, and its request element is not made available. (The 
request element is assumed to be used in a subsequent asynchronous 
exit.) 

You may use registers 10 through 13 in an abnormal end appendage 
without saving and restoring their contents. 



Block Multiplexer Channel Programming Notes 

Command retry is a new function of the block multiplexer channel 
supporting the 333 Disk Storage and the 2305 Fixed Head Storage 
devices. When the channel receives a retry request, it repeats the 
execution of the channel command word (CCW) requiring no additional 
input/output interrupts. For example, a control unit may initiate a 
retry procedure to recover from a transient error. 
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A command retry during the execution of a channel program may cause 
any of the following conditions to be detected by the initiating 
program: 

• Modifying CCWs : A CCW used in a channel program must not be 
modified before the CCW operation has been successfully completed. 
Without the command retry function, a command was fetched only once 
from storage by a channel. Therefore, a program could determine 
through condition codes or program controlled interruptions (PCI) 
that a CCW had been fetched and accepted by the channel. This 
permitted the CCW to be modified before re-execution. With the 
command retry function, this can not be done, since the channel will 
fetch the CCW from storage again on a command retry sequence. In 
the case of data chaining, the channel will command retry starting 
with the first CCW in the data chain. 

• Program Controlled Interrupts : A CCW containing a PCI flag may 
cause multiple program controlled interruptions to occur. This 
happens if the PCI flagged CCW was retried during a command retry 
procedure, and a PCI could be generated each time the CCW is 
re-executed. 

• Residual Count : If a channel program is prematurely terminated 
during the retry of a command, the residual count in the channel 
status word (CSW) will not necessarily indicate the extent of main 
storage used. For example, if the control unit detects a "wrong 
length record" error condition, an erroneous residual count is 
stored in the CSW until the command retry is successful. When the 
retry is successful, the residual in the CSW is the correct length 
of the data transfer. Since the channel will not allow more data to 
be transferred than is specified in the count field of the CCW, this 
situation will occur only when reading variable records or unknown 
record types. 

• Command Address : When data chaining with command retry, the CSW may 
not indicate how many CCWs have been executed at the time of a PCI. 

For example: 

CCW# Channel Program 

1 Read data chain 

2 Read data chain 

3 Read data chain, PCI 

4 Read command chain 

In this example, assume that the control unit signals command retry 
on Read #3 and the CPU accepts the PCI after the channel resets the 
command address to Read #1 because of command retry. The CSW stored 
for the PCI will contain the command address of Read #1, when 
actually the channel has progressed to Read #3. 

• "Bit Spinning" on Data Read : Any program that tests a data storage 
location to determine when a CCW has been executed and continues to 
execute based on this data may get incorrect results if an error is 
detected and the CCW is retried. An example of this is a PCI 
appendage in which ones are placed in a buffer area that will be 
overlayed with zeros when a record is read. When the PCI appendage 
is entered, a check for zeros is made and the appendage will 
continue to loop until the record is read into the buffer (indicated 
by ones changed to zeros). If the appendage uses the data from this 
record to modify a channel program,, the results will be 
unpredictable during a command retry sequence, as the CCW has not 
been correctly executed. 
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EXCP Programming Specifications 

This section describes the parameters of the macro instructions that you 
must use with EXCP, and the fields of the required control blocks. 

MACRO INSTRUCTIONS 

If you are using the EXCP macro instruction you must also use DCB, OPEN, 
CLOSE, and, in some cases, the EOV macro instruction. The parameters of 
these macro instructions, and of the EXCP macro instruction itself, are 
listed and explained here. A diagram of the data control block is 
included with the description of the DCB macro instruction. 

DCB — Define Data Control Block for EXCP 

The EXCP form of the DCB macro instruction produces a data control block 
that can be used with the EXCP macro instruction. You must issue a DCB 
macro instruction for each data set to be processed by your channel 
programs. Notation conventions and format illustrations of the DCB 
| macro instruction are given in the Data Management Macro Instructions 
publication. DCB parameters that apply to EXCP may be divided into four 
categories, depending on the following portions of the data control 
block that are generated when they are specified: 

• Foundation block . This portion is required and is always 12 bytes 
in length. You must specify two of the parameters in this category. 

• EXCP interface . This portion is optional. If you specify any 
parameter in this category, 20 bytes are generated. 

• Foundation block extension and common interface . This portion is 
optional and is always 20 bytes in length. If this portion is 
generated, the device dependent portion is also generated. 

• Device dependent . This portion is optional and is generated only if 
the foundation block extension and common interface portion is 
generated. Its size ranges from 4 to 20 bytes, depending on 
specifications in the DEVD parameter of this category. However, if 
you do not specify the DEVD parameter (and the foundation extension 
and common interface portion is generated) , the maximum 20 bytes for 
this portion are generated. 

Some of the procedures performed by the system when the data control 
block is opened and closed (such as writing file marks for output data 
sets on direct access volumes) require information from optional data 
control block fields. You should make sure that the data control block 
is large enough to provide all information necessary for the procedures 
you want the system to handle. 

Figure EXCP1 shows the relative position of each portion of an opened 
data control block. The fields corresponding to each parameter of the 
DCB macro instruction are also designated, with the exception of DDNAME, 
which is not included in a data control block that has been opened. The 
fields identified in parentheses represent system information that is 
not associated with parameters of the DCB macro instruction. 

Sources of information for data control block fields other than the 
DCB macro instruction are data definition (DD) statements, data set 
labels, and data control block modification routines. You may use any 
of these sources to specify DCB parameters. However, if a portion of 
the data control block is not generated by the DCB macro instruction, 
the system does not accept information intended for that portion from 
any alternative source. 
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FOUNDATION BLOCK PARAMETERS ; 

DDNAME=symbol 

The name of the data definition (DD) statement that describes the 
data set to be processed- This parameter must be given. 

MACRF=(E) 

The EXCP macro instruction is to be used in processing the data 
set. This parameter must be given. 

REPOS= Y 
N 

Magnetic tape volumes: 

If your system generation statements include the dynamic device 

reconfiguration (DDR) entry, then this parameter controls whether 

the DDR routine will attempt to reposition the volume after 

swapping devices. (To have the DDR routine attempt to reposition 

your tape volume, you must maintain the block count in the DCBBLKCT 

field.) 

Y - Yes, attempt to reposition. 

N - No, do not attempt to reposition. 

If the entry is omitted, N is assumed. 

EXCP INTERFACE PARAMETERS : 

EOEA=symbol 

2-byte identification of an end-of-extent appendage that you have 
entered into the SVC library. (See Note A. ) 

PCIA=symbol 

2-byte identification of a program controlled interruption (PCI) 
appendage that you have entered into the SVC library. 
(See Note A.) 

SIOA=symbol 

2-byte identification of a start I/O (SIO) appendage that you have 
entered into the SVC library. (See Note A. ) 

CENDA=symbol 

2-byte identification of a channel end appendage that you have 
entered into the SVC library. (See Note A. ) 

XENDA=symbol 

2-byte identification of an abnormal end appendage that you have 
entered into the SVC library. (See Note A.) 

OPTCD=code 

A code of Z indicates that for magnetic tape (input only) a reduced 
error recovery procedure (5 reads only) will occur when a data 
check is encountered. It should be specified only when the tape is 
known to contain errors and the application does not require that 
all records be processed. Its proper use would include error 
frequency analysis in the SYNAD routine. Specification of this 
parameter will also cause generation of a foundation block 
extension. This parameter is ignored unless it was selected at 
system generation. 

IMSK=value 

Any specification indicates that the system will not use IBM 
supplied error routines. 
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Note A ; The full name of an appendage is eight bytes in length, but the 
first six bytes are required by IBM standards to be the characters 
IGG019. You provide the last two characters as the 2-byte 
identification; they may range in collating sequence from WA to Z9. 



DCB 
Address 

+ 4 



+ 8 
+ 12 
+ 16 
+ 20 
+ 24 
+ 28 
+ 32 

+ 36 

+ 40 
+ 44 
+ 48 
+ 52 
+ 56 
+ 60 
+ 64 
+ 68 



The device dependent portion of 
the data control block varies 
in length and format according 
to specifications in the DSORG 
and DEVD parameters. Illustra- 
tions of this portion for each 
device type are included in 
the description of the DEVD 
parameter. 



BUFNO 


1 

1 
± 


BUFCB 






BUFL 


T 

1 
1 


DSORG 


IOBAD 


BFTEK, 

BFALN 
HIARCHY 


T 
1 
1 

1 

1 


EODAD 




RECFM 


T 
1 
1 


EXLST 




(TIOT) 




T 
1 
1 


MACRF 


( IFLGS) 


T 

1 
1 


(DEB Address) 


(OFLGS) 
OPTCD 


T 
1 
1 

— + 

1 
1 


Reserved 
Reserved 


Reserved 




EOEA 


T 
1 
1 

4- — 


PC I A 




SIOA 


T 
1 
1 


CENDA 




XENDA 


T 
1 
1 


Reserved 



Device 
Dependent 



Common 
Interface 




Foundation Block 
Extension 



Foundation Block 



EXCP Interface 



Figure EXCP1. Data Control Block Format for EXCP (After OPEN) 



Execute Channel Program (EXCP) Macro Instruction 63 



FOUNDATION BLOCK EXTENSION AND COMMON INTERFACE PARAMETERS : 

EXLST=relexp 

specifies the address of an exit list that you have written for 
exceptional conditions. The format of this exit list is given in 
the Data Management Services publication. 

EODAD=relexp 

specifies the address of your end-of-data set routine. If this 
routine is not available when it is required, the task is 
abnormally terminated. 

DSORG=code 

specifies the data set organization as one of the following codes. 
Each code indicates that the format of the device dependent portion 
of the data control block is to be similar to that generated for a 
particular access method: 

Code DCB Format for 



PS 


QSAM or BSAM 


PO 


BPAM 


DA 


BDAM 


IS 


QISAM or BISAM 



Note : For direct access devices, if you specify either PS or PO, you 

must maintain the following fields of the device dependent portion of 

the data control block so that the system can write a file mark for 
output data sets: 

• The track balance (TRBAL) field, which contains a 2-byte binary 
number that indicates the remaining number of bytes on the current 
track. 

• The full disk address (FDAD-MBBCCHHR) field, which indicates the 
location of the current record. 

IOBAD=relexp 

specifies the address of an input/output block (IOB). If a pointer 
to the current IOB is not required, you may use this field for any 
purpose . 

The following parameters are not used by the EXCP routines but 
provide cataloging information about the data set. This information can 
be used later by access method routines that read or update the data 
set. 

RECFM=code 

specifies the record format of the data set. Record format codes 
are given in the Data Management Macro Instructions publication. 
When writing a data set to be read later without EXCP, the RECFM, 
LRECL, and BLKSIZE should be specified to identify the data set 
attributes. LRECL and BLKSIZE can only be specified in a JCL 
statement, since these fields do not exist in a DCB used by EXCP. 

BFTEK=£S|E} 

specifies the buffer technique as either simple or exchange. BFTEK 
bits and 5 specify whether hierarchy or hierarchy 1 is used to 
form the buffer pool. If HIARCHY={0 jl} is omitted from the DCB, 
the buffer pool is formed in hierarchy 0. 
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BFALN={F|D} 

specifies the word boundary alignment of each buffer as either 
fullword or doubleword. 

BUFL=absexp 

specifies the length in bytes of each buffer; the maximum length is 
32,767. 

BUFNO=absexp 

specifies the number of buffers assigned to the associated data 
set; the maximum number is 255. 

BUFCB=relexp 

specifies the address of a buffer pool control block, i.e., the 
8-byte field preceding the buffers in a buffer pool. 

DEVICE DEPENDENT PARAMETERS: 



DEVD=code 

specifies the device on which the data set may reside as one of the 
following codes. The codes are listed in order of descending space 
requirements for the data control block: 



Code 

DA 
TA 
PT 
PR 
PC 
RD 



Device 

Direct access 
Magnetic tape 
Paper tape 
Printer 
Card punch 
Card reader 




Note : If you do not wish to select a specific device until job set up 
time, you should specify the device type requiring the largest area. 

The following diagrams illustrate the device dependent portion of the 
data control block for each device type specified in the DEVD parameter, 
and for each data set organization specified in the DSORG parameter. 
Fields that correspond to device dependent parameters in addition to 
DEVD are indicated by the parameter name. For special services, you may 
have to maintain the fields shown in parentheses. The special services 
are explained in the note that follows the diagram. 

Device dependent portion of data control block when DEVD=DA and 
DSORG=PS or PO: 



DCB , T 

Address + 4 JReservdj 
j. j 



+ 8 



(FDAD - MBBCCHHR) 



I T 1 

+12 | | DVTBL | Reserved j 
+16 |KEYLEN | DEVT | (TRBAL) | 

L J. J. J 



Note : For output data sets, the system uses the contents of the full 
disk address (FDAD-MBBCCHHR) field plus one to write a file mark when 
the data control block is closed, provided the track balance (TRBAL) 
field indicates that space is available. You must maintain the contents 
of these two fields yourself if the system is to write a file mark. 
OPEN will initialize DVTBL and DEVT. 



Execute Channel Program (EXCP) Macro Instruction 65 



Device dependent portion of data control block when DEVD=DA and 
DSORG=IS or DA: 

DCB r T -, 

Address +16 |KEYLEN | Reserved | 

L _J I 

Device dependent portion of data control block when DEVD=TA and 
DSORG=PS: 



DCB r n 

Address +12 | BLKCT | 

[. T T T j 

+16 JTRTCH |Reservd|DEN |Resrvdj 
l j. jl ± J 



Note ; For output data sets, the system uses the contents of the block 
count (BLKCT) field to write the block count in trailer labels when the 
data control block is closed, or when the EOV macro instruction is 
issued. You must maintain the contents of this field yourself if the 
system is to write the correct block count- 
When using EXCP to process a tape data set open at a checkpoint, you 
must be careful to maintain the correct count; otherwise the system may 
position the data set incorrectly when restart occurs. 

If your system generation statements include the dynamic device 
reconfiguration entry, this field must be maintained by you for 
repositioning. Also, your DCB macro instruction must include the 
REPOS=Y entry. 

Device dependent portion of data control block when DEVD=PT and 
DSORG=PS: 

DCB r T T 

Address +16 |CODE | Reserved | 
l x j 



Device dependent portion of data control block when DEVD=PR and 
DSORG=PS: 

DCB r T -, 

Address +16 |PRTSP | Reserved | 

L X J 



Device dependent portion of data control block when DEVD=PC or RD and 
DSORG=PS: 

DCB r f -, 

Address +16 j MODE, STACK j Reserved j 

L J. J 



The following parameters pertain to specific devices and may be 
specified only when the DEVD parameter is specified. 

KEYLEN=value 

specifies, for direct access devices, the length in bytes of the 
key of a physical record, with a maximum value of 255. When a 
block is read or written, the number of bytes transmitted is the 
key length plus the record length. 
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CODE=value 

specifies, for paper tape, the code in which records are punched as 
follows : 



Value 



Code 



I 

F 
B 
C 
A 
T 
N 


IBM BCD 

Friden 

Burroughs 

National Cash Register 

ASCII 

Teletype 

no conversion (format F records only) 



If this parameter is omitted, N is assumed. 



DEN=value 

specifies, for magnetic tape, the tape recording density in bits 
per inch as follows: 







1 




Density 






Value 


L 










r 


Model 


T ~ 
1 


Model 








2400/3400 


1 


2400/3400 








7-track 


1 


9 -track 


L 




4- - 




4. 




r 




T 




T 











200 


1 


- 




1 




556 


1 


- 




2 




800 


1 


800 




3 




- 


1 


1600 



H 




If this parameter is omitted, the lowest density is assumed. 

TRTCH=value 

specifies, for 7-track magnetic tape, the tape recording technique 
as follows: 



Value 
C 

E 



Tape Recording Technique 

Data conversion feature is available. 

Even parity is used. (If omitted, odd parity is 
assumed.) 



BCDIC to EBCDIC translation is required. 



MODE=value 

specifies, for a card reader or punch, the mode of operation. 
Either C (column binary mode) or E (EBCDIC code) may be specified. 

STACK=value 

specifies, for a card punch or card reader, the stacker bin to 
receive cards as either 1 or 2. 



PRTSP=value 

specifies, for a printer, the line spacing as either 0, 1, 2, or 3. 
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OPEN — Initialize Data Control Block 

The OPEN macro instruction initializes one or more data control blocks 
so that their associated data sets can be processed. You must issue 
OPEN for all data control blocks that are to be used by your channel 
programs. (A dummy data set may not be opened for EXCP. ) Some of the 
procedures performed when OPEN is executed are: 

• Construction of data extent block (DEB) . 

• Transfer of information from DD statements and data set labels to 
data control block. 

• Verification or creation of standard labels. 

• Tape positioning. 

• Loading of programmer-written appendage routines. 

The three parameters of the OPEN macro instruction are: 

dcb-addr 

specifies the address of the data control block to be initialized. 
(More than one data control block may be specified. ) 

optj. 

specifies the intended method of I/O processing of the data set. 
You may specify this parameter as either INPUT, RDBACK, or OUTPUT. 
For each of these, label processing when OPEN is executed is as 
follows : 

INPUT - Header labels are verified. 
RDBACK - Trailer labels are verified. 
OUTPUT - Header labels are created. 

If this parameter is omitted, INPUT is assumed. 

specifies the volume disposition that is to be provided when volume 
switching occurs. The operand values and meanings are as follows: 

REREAD Reposition the volume to process the data set again. 

LEAVE No additional positioning is performed at end-of -volume 
processing. 

DISP The disposition indicated on the DD statement is tested 
and appropriate positioning provided. This service is 
assumed if this operand is omitted and volume 
positioning is applicable. If there is no disposition 
specified in the DD statement when this operand is 
specified, LEAVE is assumed. 

OPEN processes the EXCP macro as a combination of the DSORG specified 
in the DCB and physical sequential (PS). The DSORG specified in the DCB 
only affects the merging of certain DSCB, JFCB, and DCB fields. For all 
other operations, EXCP is considered to have a DSORG of PS. Only one 
volume is processed for EXCP by the OPEN routine, except when there are 
concatenated partitioned data sets, in which case all volumes concerned 
are processed. Thus, direct access and indexed sequential organized 
data sets will have only the first volume processed by OPEN. 

The list and execute forms of the OPEN macro instruction are 
described in the Data Management Macro Instruction publication. 



opt 



2 
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EXCP — Execute Channel Program 

The EXCP macro instruction requests the initiation of the I/O operations 
of a channel program. You must issue EXCP whenever you want to execute 
one of your channel programs. The only parameter of the EXCP macro 
instruction is: 

iob-addrx 

specifies the address, or a register that contains the address of 
the input/output block of the channel program to be executed. 

EOV — End of Volume 

The EOV macro instruction identifies end-of-volume and end-of-data set 
conditions. For an end-of-volume condition, EOV causes switching of 
volumes and verification or creation of standard labels. For an 
end-of-data set condition, EOV causes your end-of-data set routine to be 
entered. Before processing trailer labels on a tape input data set, you 
must decrement the DCBBLKCT field. You issue EOV if switching of 
magnetic tape or direct access volumes is necessary, or if secondary 
allocation is to be performed for a direct access data set opened for 
output. 

For magnetic tape, you must issue EOV when either a tapemark is read 
or a reflective spot is written over. In these cases, bit settings in 
the 1-byte OFLGS field of the data control block determine the action to 
be taken when EOV is executed. Before issuing EOV for magnetic tape, 
you must make sure that appropriate bits are set in OFLGS. Bit 
positions 2, 3, 6, and 7 of OFLGS are used only by the system; you are 
concerned with bit positions 0,1,4, and 5. The use of these OFLGS bit 
positions is as follows: 

Bit 

indicates that a tape mark is to be written. 
Bit 1 

indicates that a backwards read was the last I/O operation. 
Bit 4 

indicates that data sets of unlike attributes are to be 

concatenated. 
Bit 5 

indicates that a tape mark has been read. 

If bits and 5 of OFLGS are both off when EOV is executed, the tape 
is spaced past a tapemark, and standard labels, if present, are verified 
on both the old and new volumes. The direction of spacing depends on 
bit 1. If bit 1 is off, the tape is spaced forward; if bit 1 is on, the 
tape is backspaced. 

If bit is on when EOV is executed, a tapemark is written 
immediately following the last data record of the data set, standard 
labels, if specified, are created on the old and the new volume. 

When issuing EOV for sequentially organized output data sets on 
direct access volumes, you can determine whether additional space has 
been obtained on the same or a different volume. You do this by 
checking the volume serial number in the unit control block (UCB) both 
before and after issuing EOV. 

The only parameter of the EOV macro instruction is : 

dcb-addrx 

specifies the address of the data control block that is opened for 
the data set. If this parameter is specified as (1) , register 1 
must contain this address. 
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CLOSE — Restore Data Control Block 

The CLOSE macro instruction restores one or more data control blocks so 
that processing of their associated data sets can be terminated. You 
must issue CLOSE for all data control blocks that were used by your 
channel programs. Some of the procedures performed when CLOSE is 
executed are : 

• Release of data extent block (DEB) . 

• Removal of information transferred to data control block fields when 
OPEN was executed. 

• Verification or creation of standard labels. 

• Volume disposition. 

• Release of prog rammer- written appendage routines. 

The two parameters of the CLOSE macro instruction are: 

dcb-addr 

specifies the address of the data control block to be restored. 
More than one data control block may be specified. 

opt 

specifies the type of volume disposition intended for the data set. 
You may specify this parameter as either LEAVE or REREAD. The 
corresponding volume disposition when CLOSE is executed is as 
follows : 

LEAVE - Volume is positioned at logical end of data set. 

REREAD - Volume is positioned at logical beginning of data set. 

DISP - The disposition indicated on the DD statement is tested, 
and appropriate positioning is provided. This service is 
assumed if this operand is omitted and volume positioning 
is applicable. If there is no disposition specified in 
the DD statement when this operand is specified, LEAVE is 
assumed. 

This parameter is ignored if specified for volumes other than 
magnetic tape or direct access. 

Note: When CLOSE is issued for data sets on magnetic tape volumes, 
labels are processed according to bit settings in the OFLGS field of the 
data control block. Before issuing CLOSE for magnetic tape, you must 
set the appropriate bits in OFLGS. The OFLGS bit positions that you are 
concerned witn are listed in the EOV macro instruction description. 

The list and execute forms of the CLOSE macro instruction are 
described in the Data Management Macro Instructions publication. 



CONTROL BLOCK FIELDS 

The fields of the input/output block, event control block, and data 
extent block are illustrated and explained here; the data control block 
fields have been described with the parameters of the DCB macro 
instruction in the section "EXCP Programming Specifications." 

Input/Output Block Fields 

The input/ output block is not automatically constructed by a macro 
instruction; it must be defined as a series of constants and must be on 
a fullword boundary. For unit record and tape devices, the input/ output 
block is 32 bytes in length. For direct access, teleprocessing, and 
graphic devices, 8 additional bytes must be provided. 
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In Figure EXCP2, the shaded areas indicate fields in which you must 
specify information. The other fields are used by the system and must 
be defined as all zeros. You may not place information into these 
fields, but you may examine them. 



I OB Address 





Direct 
Access 
>- Storage 
Devices 
(DASD) 



Figure EXCP2. Input/Output Block Format 



Flags 1 (1 byte) 

specifies the type of channel program. You must set bit positions 
0, 1, and 6. One bits in positions and 1 indicate data chaining 
and command chaining, respectively. (If both data chaining and 
command chaining are specified, the system does not use error 
recovery routines except for the 2311, 2671, 1052, and 2150.) A 
one bit in position 6 indicates that the channel program is not 
related to any other channel program. Bit positions 2, 3, 4, 5, 
and 7 are used only by the system. 

Flags 2 (1 byte) 

is used only by the system. 

First two sense bytes (2 bytes) 

are placed into the input/output block by the system when a unit 
check occurs. 

ECB code (1 byte) 

indicates the first byte of the completion code for the channel 
program. The system places this code in the high order byte of the 
event control block when the channel program is posted complete. 
The completion codes and their meanings are listed under "Event 
Control Block Fields." 

ECB address (3 bytes) 

specifies the address of the 4 -byte event control block that you 
have provided. 

Flags 3 (1 byte) 

is used only by the system. 



Execute Channel Program (EXCP) Macro Instruction 71 



Channel status word (7 bytes) 

indicates the low order seven bytes of the channel status word, 
which are placed into this field each time a channel end occurs. 

SIO code (1 byte) 

indicates, in the high- order four bits, the instruction length, and 
in the low-order four bits, the condition code for the SIO 
instruction that the system issues to start the channel program. 

Channel program address (3 bytes) 

specifies the starting address of the channel program to be 
executed., 

Reserved (1 byte) 

is used only by the system. 

DCB address (3 bytes) 

specifies the address of the data control block of the data set to 
be read or written by the channel program. 

Reposition modifier (1 byte) 

is used by the system for volume repositioning in error recovery 
procedures. 

Restart address (3 bytes) 

is used by the system to indicate the starting address of a channel 
program that performs special functions for error recovery 
procedures. The system also uses this field in procedures for 
making request elements available, as explained under "Error 
Recovery Procedures for Related Channel Programs." 

Block count increment (2 bytes) 

specifies, for magnetic tape, the amount by which the block count 
(BLKCT) field in the device dependent portion of the data control 
block is to be incremented. You may alter these bytes at any time. 
For forward operations, these bytes should contain a binary 
positive integer (usually + 1); for backward operations, they 
should contain a binary negative integer. When these bytes are not 
used, all zeros must be specified. 

Error counts (2 bytes) 

indicates the number of retries attempted during error recovery 
procedures. 

M (1 byte) 

Direct access devices: 

Extent entry in the data extent block that is associated with the 

channel program. (0 indicates the first extent; 1 indicates the 

second, etc.) 

Teleprocessing and graphic devices: 

The UCB index. 

BBCCHHR (7 bytes) 

specifies, for direct access devices, the seek address for the 
programmer's channel program. 

Event Control Block Fields 

You must define an event control block as a 4-byte area on a fullword 
boundary. When the channel program has been completed, the input/output 
supervisor places a completion code containing status information into 
the event control block (Figure EXCP3). Before examining this 
information, you must test for the setting of the "Complete Bit." If 
the complete bit is not on, and the problem program cannot perform other 
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useful operations, you should issue a WAIT macro instruction that 
specifies the event control block. Under no circumstances may you 
construct a program loop that tests for the complete bit. 

r t t 1 

| WAIT | Complete | Remainder of Completion Code | 

I Bit=0 | | | 

I I Bit=l | | 

L J. X J 

12 31 

Figure EXCP3. Event Control Block After Posting of Completion Code 

WAIT bit 

A one bit in this position indicates that the WAIT macro 
instruction has been issued, but that the channel program has not 
been completed. 

Complete bit 

A one bit in this position indicates that the channel program has 
been completed; if it has not been completed, a zero bit is in this 
position. 

Completion code 

This code, which includes the WAIT and complete bits, may be one of 
the following 4-byte hexadecimal expressions: 

Code Interpretation 

7F000000 Channel program has terminated without error. 

41000000 Channel program has terminated with permanent 
error. 

42000000 Channel program has terminated because a direct 
access extent address has been violated. 

44000000 Channel program has been intercepted because of 
permanent error associated with device end for 
previous request. You may reissue the 
intercepted request. 

48000000 Request element for channel program has been 
made available after it has been purged. 

4B000000 One of the following errors occurred during 
tape error recovery processing: 

• The CSW command address in the IOB is 
zeros. 

• An unexpected load point was encountered. 

4F0 00000 Error recovery routines have been entered 

because of direct access error but are unable 
to read home address or record 0. 

50000000 Channel program terminated with error. Input 
block was a DOS embedded checkpoint record. 

Data Extent Block Fields 

The data extent block is constructed by the system when an OPEN macro 
instruction is issued for the data control block. You may not modify 
the fields of the data extent block, but you may examine them. The data 
extent block format and field description is contained in the System 
Control Block publication. 
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Appendix: RESTORE and PURGE Macro Instructions 

If you want to use the RESTORE or PURGE macro instruction, you must 
either add the macro definitions to the macro-library (SYSl.MACLIB) or 
place them in a separate partitioned data set and concatenate this data 
set to the macro-library. This section contains the following : 

• The format of the macro instruction,. 

• The job control and utility statements needed to add the macro 
definition to the library. 

• The macro definition to be added to the library. 



RESTORE Macro Instruction 

This macro instruction is used to return purged request elements to the 
request queues. The format of this macro instruction is as follows: 

r t t 1 

| Name j Operation j Operand | 

f + + ___ j 

| | RESTORE | User purge IOB address | 

L I X _J 

The user purge IOB address is the address of a pointer to the first IOB 
address in a previously purged IOB list. It could be the DEBUSRPG field 
in the data extent block (see "SVC Purge Routine"). 

RESTORE Macro Definition 



SNAME 



&NAME 



.El 



MACRO 












RESTORE 


&LIST 










AIF 


(■gLIST* 


EQ 


") 


.El 




IHBINNRA 


&LIST 








LOAD REG 1 


SVC 


17 








ISSUE SVC FOR RESTORE 


MEXIT 












IHBERMAC 


01,150 








LIST ADDR MISSING 


MEND 













Control Statements Required 



// jobname 

//stepname 

//SYSPRINT 

//SYSUT2 

//SYSIN 

./ ADD 



./ 
/* 



JOB {parameters} 

EXEC PGM=IEBUPDTE,PARM=NEW 

DD SYSOUT=A 

DD DSNAME=SYSl.MACLIB,DISP=OLD 

DD DATA 

NAME=RESTORE , LIST=ALL 



RESTORE Macro definition 



ENDUP 
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PURGE Macro Instruction 



The PURGE macro instruction is used to return request elements to the 
I/O supervisor inactive queue (next available) . 



PURGE Macro Definition 





MACRO 












&NAME 


PURGE 


&LIST 












AIF 


('&LIST' 


EQ" 


•) 


.El 




&NAME 


IHBINNRA 

SVC 

MEXIT 


&LIST 
16 








LOAD REG 1 


.El 


IHBERMAC 
MEND 


01,147 








LIST ADDR 



Control Statements Required 



// jobname 

//stepname 

//SYSPRINT 

//SYSUT2 

//SYS IN 

./ ADD 



JOB {parameter} 

EXEC PGM=IEBUPDTE,PARM=NEW 

DD SYSOUT=A 

DD DSNAME=SYSl.MACLIB,DISP=OLD 

DD * 

NAME=PURGE , LIST=ALL 




1 



./ 
/* 



PURGE Macro definition 



ENDUP 



L J 



r t t 

I Name | Operation | Operand 



-H 



| symbol | PURGE 

L I 



| User purge parameter list 

.x 



The purge parameter list is constructed in the user's program area. 
Depending on the options specified in the PURGE parameter list, elements 
can be purged from 

1. The asynchronous exit queue of the task supervisor. 

2. The request blocks chained to the TCB. 

3. The I/O supervisor logical channel queues. 
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You can bypass the purge of the RBs chained to the TCB by setting bit 
5 of the option byte. The parameter list is constructed prior to 
issuing the PURGE macro instruction; this list must fall on a fullword 
boundary. It is either a three-word list or, if bit 4 of the options 
byte in Word 1 equals one (1) , a four-word list. It is constructed as 
follows : 



Word 1 



Byte 1 

(options byte) 



r 1 

Bit - Specified DEB or DEB chain 

=0 - Purge request elements associated with complete DEB chain 
starting at the DEB specified in bytes 2, 3, and 4 of 
word 1. 
=1 - Purge only the request elements associated with the DEB 
specified by bytes 2, 3, and 4 of word 1. 



Bit 1 - POST request purged or ignore posting. 
=0 - Do not POST the purged requests. 
=1 - POST the purge requests, code = X*48'. 



Bit 2 - HALT I/O or quiesce active requests. 
=0 - Allow the active requests to quiesce. 

=1 - HALT the I/O operations. (The HALT I/O is simulated if 
the operation is a SEEK. 



Bit 3 - Purge all or only related requests . 
=0 - Purge all requests. 
=1 - Purge only related requests. 



Bit 4 - Normal purge or list purge. 
=0 - Normal purge. 
=1 - Purge TCB list. 



Bit 5 - Purge all queues or bypass RB purge. 

=0 - Purge AEQ f RB, and I/O supervisor logical channel queues. 
=1 - Purge only the I/O supervisor logical channel queue (s) 
and AEQ. 
j. j 

Bit 6 - Purge by TCB or DEB 
=0 - Purge by DEB 
=1 - Purge by TCB 

Note ; This bit must be zero in order to honor bit 0. 
If this bit is one, all requests associated with the TCB 
are purged, and bit is ignored. 
f 

| Bit 7 - (Spare) 

L_. 



Bytes 2, 3. and 4 

DEB address - not required if purging by TCB. 



Word 2 



Byte 1 

completion code 

Bytes 2, 3, and 4 

TCB address - if none, the current TCB is used. 
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Word 3 



Byte 1 



Quiesce indicator field. It will indicate X'Ol* 
more requests are quiescing. 



if one or 



Bytes 2, 3. and 4 

Address of the initial link field for chaining IOBs that are 
purged. The initial link field can be the user purge field in 
the DEB (DEBUSRPG) or any area you select. The initial link 
field points to the first IOB in the chain. At the completion 
of purge, the contents of word 3 are unpredictable. No 
chaining is done when TCB with HALT I/O option is specified. 

If the IOB restart field (IOBRESTR) is used as a link field, 
the last one will contain X'FFFFFF' in its three low-order 
bytes. 

The following figure shows the IOB chain. 



Chaining IOBs 



j DEBUSRPG Of DEB, | 

-*i or other initial \- 

| link field | 

L I 




Word 3 



IOB 

r T 

I I I 

IOBRESTR | | 

f J | 

L J 

IOB 

r 1 

I 1 I 

IOBRESTR | | 
| FFFFFF | | 
h J | 

L J 



IOB Chain for PURGE 
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Word 4 



Byte 1 

(flag byte) 



| Bit 1 - Purge or wait flag. 
| =0 - Purge entry. 
| =1 - Wait entry. 



j. 

| Bit 2 - 



Wait flag. 
=0 - Return to caller before waiting. 
=1 - Perform purge and wait operations, and do not return to 

caller. 



JBits 3-8 - Reserved. 

l 



Bytes 2,3, and U 

Address of the QUIESCE I/O parameter list (QPL). This field 
points to a list of TCBs that are to be purged. The format of 
the list is shown below. 



L_. 



Word 4 



|1 |2 
-H Count | Reserved 
| Field | 
j. + 

|5 |6 

j j Chain Field 



j. + 1 

|9 |10 

QPL j Address of TCB 
| Flags j 

L J. 



r t 1 

1 5+n |6+n | 

| j Chain Field j 



1 



j. + 

|9+n jlO+n | 

j QPL | Address of TCB| 
| Flags | | 

L J. J 



n = 8x(# of TCBs to be purged -1) 

Count field. 

A temporary count field used to keep track of the number of TCBs 
that have been purged. 

Chain field. 

Address of the initial link field for chaining IOBs that are 
purged. See the illustration for chaining IOBs in this section. 
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QPL flags - Last entry or current entry, 

Bit - Last entry flag. 

=0 - More entries follow. 
=1 - Last entry. 

Bit 1 - Current entry flag. 
=0 - Not current. 
=1 - Current. 

Bits 2-8 - Reserved. 

TCB address. 

Address of the TCB to be purged. 
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ATLAS- -Assign an Alternate Track and Copy Data From the Defective 
Track 

A program that uses the EXCP macro instruction for input and output may 
use the ATLAS macro instruction, during the execution of the program, to 
obtain an alternate track and to copy a defective track onto the 
alternate track. With the use of ATLAS, the program can recover from 
permanent (hard) errors encountered in the execution of the following 
types of I/O commands: 

• Search ID. 

• Write. 

(The error condition must be confirmed during the execution of the 
channel program by a CCW that checks the data written.) 

• Read count. 

Errors in the CCHHR part of the count area can be recovered from 
unless the record is the home address or record zero. 

Errors in the KDD part of the count area cannot be recovered from 
unless the user has identified the defective record. 

Your DCB must include the DCBRECFM field and the field must show 
whether the data set is in the track overflow format. If it is, 
recovery from errors in last records on tracks depends on your 
identifying the track overflow record segments. 

Recovery takes the form of obtaining an alternate good track and 
copying the defective track onto the good alternate one. Unless a 
re-execution of the channel program by ATLAS can correct the defect, the 
user should examine, and if necessary replace, defective records in a 
subsequent job if the data set is to be processed again. 

ATLAS MACRO INSTRUCTION 

The format of the macro instruction is: 

r t t 1 

| Name | Operation! Operands | 

j. 4 + j 



(symbol) j ATLAS JPARMADR=< > ,CHANPRG 



address \ 
(register)/ 



(nr) 

(2) (YES) 

\\ ' wEiTs ioJ 



, CNTPTR=< 

L L ± J 

PARMADR 

Address of a parameter address list of the following format: 

r 1 

Address of the parameter address list 



r 

•■J +0 Address of the IOB for the channel program that 
j encountered the error 
j. 

| +4 Main storage address of the count area field 

i 

The count area field contains the CCHHRKDD of a defective 
record or the CCHH of a track that is to be copied. 
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address - Address is given as the symbolic label of the address 
list. 

(register) - Address is given as the number of a general register 
(1-12) that contains the address of the list. 

CHANPRG 

Condition of the channel program that encountered the error. 

R - Channel program may be re-executed by ATLAS. Before permitting 
re-execution of the channel program by ATLAS, you must reset 
the error indications of the previous execution fields in the 
DCBIFLGS. (See the example of the use of ATLAS below.) 

NR - Channel program may not be re-executed. 

If this parameter is omitted, R is assumed. 

,CNTPTR 

Contents of the count area field. 

P - Part of the count area - the CCHH address of the track to be 

copied. 
F - Full count area - CCHHRKDD count of the record found defective. 

If this parameter is omitted, P is assumed. 

, WRITS 

track overflow segment identification. 

If your data set is in the track overflow format, this 
identification determines recovery from errors in last records on 
tracks. 

YES - If this is the last record on the track, it is a segment 
other than the last of a track overflow record. 

NO - If this is the last record on the track, it is the last or 
only segment of a track overflow record. 

If this parameter is omitted, it is assumed that it cannot be 
established whether a last record is a segment of an overflow 
record. 

USE OF ATLAS 

If a channel program encounters a unit check condition (shown in the 
CSW) in its execution, the I/O supervisor program will place the Sense 
bytes in the IOB. ATLAS can be used to recover from Sense conditions 
shown by the following bit settings: 

IOBSENSO X*08' Data check (except in the count area) 

IOBSENSl X'SO* Data check in the count area 

I0BSENS1 X , 02* Missing address marker 

(But see the following for combinations of this 
bit setting for which ATLAS is powerless.) 

However, defects in the home address record or the record zero record 
cannot be recovered from through the use of ATLAS. These conditions are 
shown by: 

IOBSENSl X , 02 t and IOBSENSO X 1 01" - home address defect. 

IOBSENSl X^A* - record zero defect, or, 

home address cannot be located. 
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Also, before using ATLAS, you must reset error indications as follows: 
NI DCBIFLGS, X'3F f Reset the DCBIFLGS error indications. 

The ATLAS program will attempt to find a good alternate track and 
will attempt to copy the defective track onto the good track, including 
all error conditions in either key or data areas. The error conditions 
may be rectified by re-executing the channel program or through the use 
of the IEHATLAS utility program in a subsequent step. 



The following illustrates the use of the ATLAS macro instruction. 



EXCP 


MYIOB 


WAIT 


MYECB 


TM 


MYECB^X^O 1 


BO 


NEXT 


TM 


IOBCSW+S^X'Oa 


BL 


OTHER 


TM 


IOBSENS0,X*0 8 


BO 


ATLASGO 


TM 


IOBSENSl,X f 80 


BO 


ATLASGO 


TM 


IOBSENSl,X f 0A 


BO 


OTHER 


ATLASGO EQU 


* 


NI 


DCBIFLGS, X*3F 


ATLAS 


PARMADR=THERE 



TEST FOR I/O ERROR 

NO, SUCCESSFUL, GO TO ANOTHER 

ROUTINE 

• UNIT CHECK 

NO, DO OTHER ERROR PROCESSING 
' DATA CHECK 

YES, VALID ERROR 

• DATA CHECK IN COUNT 
YES, VALID ERROR 

1 MISSING ADDRESS MARKER 

YES, ATLAS CANNOT HANDLE ERROR 
DO OTHER ERROR PROCESSING 

1 RESET ERROR INDICATORS 
,CHANPRG=R 



OPERATION OF THE ATLAS PROGRAM 
The ATLAS program (SVC 86) : 

• Establishes the availability and address of the next alternate track 
from the format 4 DSCB of the VTOC. 

• Brings all count fields from the defective track into main storage 
to establish the description of the track. 

• Initializes the alternate track. (Write home address, write record 
zero. ) 

• Brings the key and data areas of each record into main storage, one 
at a time, and combines them with their new count area to write the 
complete record onto the alternate track. 

• When the copying is finished, chains the alternate to the defective 
track and updates the VTOC. 



RETURN CODES 

When control returns to the user, he will find one of the following 
decimal return codes in register 15: (Note that for return codes 0, 36, 
40, and 44 the contents of register may be significant.) 
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Decimal 

Return Meaning 

Code 

- Successful completion. 

Key and data areas have been copied from the defective track onto 
a good alternate one- The only error encountered was in the 
record identified by the user's CCHHRKDD value. 

If the channel program is re- executable, it has been successfully 
re-executed. 

4 - This device type (2301 drum, 2303 drum) does not have alternate 
tracks that can be assigned by programming. 

8 - All alternate tracks for the device have been assigned. 

12 - A request for storage (GETMAIN macro instruction) could not be 
satisfied. 

16 - All attempts to initialize and transfer data to an alternate 

track failed. The number of attempts made is equal to 10% of the 
assigned alternates for the device. 

20 - The type of error shown by the sense byte cannot be handled 

through the use of the ATLAS macro instruction. The condition is 
other than a data check (in the count or data areas) or a missing 
address marker. 

24 - The format 4 DSCB of the VTOC cannot be read, therefore alternate 
track information is not available to ATLAS. 

28 - The record specified by the user was the format 4 DSCB and it 
could not be read. 

32 - An error found in count area of last record on the track cannot 
be handled because last-record-on-track identification is not 
supplied. 

36 - An error was encountered reading or writing the home address 
record or reocrd zero. No error recovery has taken place. 
If register contains X'01 00 00 00* , the defect is in record 
zero. 

40 - Successful completion. 

Key and data areas have been copied from the defective track onto 
a good alternate one- However, the alternate track may have 
records with defective key or data areas. Register identifies 
the first three found defective as follows: 




r 1 

|n R R R j 



n - Number of record numbers that follow (0, 1, 2, or 3). 

R - The number of the record found defective but copied anyhow. 

If the channel program is re- executable, it has been successfully 
re-executed. 
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44 - Error /Errors encountered and no alternate track has been 

assigned. The return parameter register (RO) will contain the R 
of a maximum of three error records. 



Error conditions that return this code are: 



2. 



ATLAS received an error indication for a record with a data 
length in the count field of zero. Recovery was not possible 
because a distinction cannot be made between an EOF record 
and an invalid data length. 

An error occurred while reading the count field of a record 
and the KDD (key length-data length) was found to be 
defective. 



3. More than three records on the specified track contained 
errors in their count fields. 

48 - No errors found on the track, no alternate assigned. ATLAS will 
not assign an alternate unless a track has at least one defective 
record. 

52 - I/O error in re-executing user's channel program. 

A good alternate is chained to the defective track and data has 
been transferred. The user's control blocks will give indication 
of the error condition causing failure in re-execution of his 
channel program. 

56 - The DCB reflects a track overflow data set but the UCB device 
type shows that the device does not support track overflow. 

60 - The CCHH of the user specified count area is not within the 
extents of his data set. 

Figures EXCP4 and EXCP5 summarize the return codes that reflect track 
error conditions by error location. 







Area in Error 


Record in Error 


Count Area 


Key Area 


Data Area 


CCHHR 


KDD 


Record r (r / 0) 


Not Last on Track 





44 


40 


40 


Last 

on 

Track 


WRITS=YES 





44 


40 


40 


WRITS=NO 





44 


40 


40 


Omitted* 


32 


44 


40 


40 


Record Zero 




36 


36 


36 


36 


Home Address 




36 





* Omitted and the Data Set is in the Track Overflow Format. 

Figure EXCP4. Error Locations and Return Codes if CCHH is in the Count 
Area Field 
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Record in Error 




Area in 


Error 




Count Area 


Key Area 


Data Area 


CCHHR 


KDD 


Record n ( n=R in CCHHRKDD) 


Not Last 


on Track 
















Last 

on 

Track 


WRITS=YES 














WRITS=NO 














Omitted * 


32 


32 








Record m (m ^ R in CCHHRKDD ) 


Not Last 


on Track 







44 


40 


40 


Last 

on 

Track 


WRITS=YES 





44 


40 


40 


WRITS=NO 





44 


40 


40 


Omitted * 


32 


44 


40 


40 


Record Zero 




36 


36 


36 


36 


Home Address 




36 






Omitted and the Data Set is in the Track Overflow Format. 



Figure EXCP5. Error Locations and Return Codes if CCHHRKDD is in the 
Count Area Field 
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Execute Direct Access Program 
(XDAP) Macro Instruction 



This chapter explains what the execute 
direct access program (XDAP) macro 
instruction does and how you can use it. 
The control block generated when XDAP is 
issued and the macro instructions used with 
XDAP are also discussed. 

The XDAP macro instruction provides you 
with a means of reading, verifying, or 
updating blocks on direct access volumes 
without using an access method and without 
writing your own channel program. Since 
most of the specifications for XDAP are 
similar to those for the execute channel 
program (EXCP) macro instruction, it is 
recommended that you be familiar with the 
"EXCP Macro Instruction" chapter of this 
publication, as well as with the 
information contained in the required 
publication. 



PREREQUISITE PUBLICATION 

The IBM System/360 Operating System; 
| Supervisor Services and Macro Instructions 
publication (GC28-6646) explains the 
standard procedures for I/O processing 
under the operating system. 
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Execute Direct Access Program (XDAP) Macro Instruction 

Execute direct access program (XDAP) is a macro instruction of 
System/ 360 Operating System that you may use to read, verify, or update 
a block on a direct access volume. If you are not using the standard 
IBM data access methods, you can, by issuing XDAP, generate the control 
information and channel program necessary for reading or updating the 
records of a data set. 

You cannot use XDAP to add blocks to a data set, but you can use it 
to change the keys of existing blocks. Any block configuration and any 
data set organization can be read or updated. 

Although the use of XDAP requires much less main storage space than 
do the standard access methods, it does not provide many of the control 
program services that are included in the access methods. For example, 
when XDAP is issued, the system does not block or deblock records and 
does not verify block length. 

To issue XDAP, you must provide the actual device address of the 
track containing the block to be processed. You must also provide 
either the block identification or the key of the block, and specify 
which of these is to be used to locate the block. If a block is located 
by identification, both the key and data portions of the block may be 
read or updated. If a block is located by key, only the data portion 
can be processed. 



Requirements for Execution of Direct Access Program 

Before issuing the XDAP macro instruction, you must issue a DCB macro 
instruction, which produces a data control block (DCB) for the data set 
to be read or updated. You must also issue an OPEN macro instruction, 
which initializes the data control block and produces a data extent 
block (DEB). 

When the XDAP macro instruction is issued, another control block, 
containing both control information and executable code, is generated. 
This control block may be logically divided into three sections: 

• An event control block (ECB), which is supplied with a completion 
code each time the direct access channel program is terminated. 

• An input/output block (IOB) , which contains information about the 
direct access channel program. 

• A direct access channel program, which consists of three channel 
command words (CCWs). The type of channel program generated depends 
on specifications in the parameters of the XDAP macro instruction. 

After this XDAP control block is constructed, the direct access channel 
program is executed. A block is located by either its actual address or 
its key, and is either read or updated. 

When the channel program has terminated, a completion code is placed 
into the event control block. After issuing XDAP, you should therefore 
issue a WAIT macro instruction specifying the event control block to 
determine whether the direct access program has terminated. If volume 
switching is necessary, you must issue an EOV macro instruction. When 
processing of the data set has been completed, you must issue a CLOSE 
macro instruction to restore the data control block. 
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XDAP Programming Specifications 

MACRO INSTRUCTIONS 

When you are using the XDAP macro instruction, you must also issue DCB, 
OPEN, CLOSE, and, in some cases, the EOV macro instruction. The 
parameters of the XDAP macro instruction are listed and described here. 
For the other required macro instructions, special requirements or 
options are explained, but you should refer to the "EXCP Macro 
Instruction" section of this publication for listings of their 
parameters . 

DCB — Define Data Control Block 

The EXCP form of the DCB macro instruction produces a data control block 
that can be used with the XDAP macro instruction. You must issue a DCB 
macro instruction for each data set to be read or updated by the direct 
access channel program. The "EXCP Macro Instruction" section of this 
publication contains a diagram of the data control block, as well as a 
listing of the parameters of the DCB macro instruction. 

OPEN — Initialize Data Control Block 

The OPEN macro instruction initializes one or more data control blocks 
so that their associated data sets can be processed. You must issue 
OPEN for all data control blocks that are to be used by the direct 
access program. Some of the procedures performed when OPEN is executed 
are: 

• Construction of data extent block (DEB) . 

• Transfer of information from DD statements and data set labels to 
data control block. 

• Verification or creation of standard labels. 

• Loading of programmer-written appendage routines. 

The two parameters of the OPEN macro instruction are the address (es) 
of the data control block (s) to be initialized, and the intended method 
of I/O processing of the data set. The method of processing may be 
specified as either INPUT or OUTPUT; however, if neither is specified, 
INPUT is assumed. 

XDAP — Execute Direct Access Program 

The XDAP macro instruction produces the XDAP control block (i.e., the 
ECB, IOB, and channel program) and executes the direct access channel 
program. The format of the XDAP macro instruction is: 

r t ~i 

| Operation | Operand | 

j. + j 

| XDAP | ecb-symbol,type-{R|W|V}{I|K},dcb-addr,area-addr | 

| j , length- value, [ (key-addr, key length-value) ] ,blkref-addr | 

[ j , sector- addr j 

L J. J 

ecb-symbol 

specifies the symbolic name to be assigned to the XDAP control 
block. 
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type-{R|W|V}{I|K} 

specifies the type of I/O operation intended for the data set and 
the method by which blocks of the data set are to be located. 

The codes and their meanings are as follows: 

R - Read a block. 

W - Write a block. 

V - Verify contents of a block but do not transfer data. 

I - Locate a block by identification. (The key portion, if 

present, and the data portion of the block are read or 

written. ) 
K - Locate a block by key. (Only the data portion of the 

block is read or written.) 

dcb-addr 

specifies the address of the data control block of the data set. 

area-addr 

specifies the address of an input or output area for a block of the 
data set. 

length-va lue 

specifies the number of bytes to be transferred to or from the 
input or output area. If blocks are to be located by 
identification and the data set contains keys, the value must 
include the length of the key. The maximum number of bytes 
transferred is 32767. 

key-addr 

specifies, when blocks are to be located by key, the address of a 
main storage field that contains the key of a block to be read or 
overwritten. 

key length-va lue 

specifies, when blocks are to be located by key, the length of the 
key. The maximum length is 255 bytes. 

blkref-addr 

specifies the address of a main storage field containing the actual 
device address of the track containing the block to be located. 
When blocks are to be located by key, this field is seven bytes in 
length; when blocks are to be located by identification, an eighth 
byte indicating block identification must be included in this 
field. (The actual address of a block is in the form MBBCCHHR, 
where M indicates which extent entry in the data extent block is 
associated with the direct access program; BB indicates the bin 
number of direct access volume; CC indicates the cylinder address; 
HH indicates the actual track address; and R indicates the block 
identification. ) 

sector-addr 

specifies the address of a one-byte field containing a sector 
value. The sector- address parameter is used for rotational 
position sensing (RPS) devices only. When the parameter is coded, 
a set-sector CCW (using the sector value indicated by the data 
address field) precedes the Search-ID-Equal command in the channel 
program. The sector- address parameter is ignored if the type 
parameter is coded as RK, WK, or VK # or is omitted in the execute 
form of the XDAP macro instruction. 

Note : No validity check is made on either the address or the 
sector value when the XDAP macro is issued. However, a unit 
exception interrupt will occur during the channel program execution 
if the sector value is larger than the maximum for the device or if 
the macro is issued against a device without RPS. 
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EOV — End of Volume 

The EOV macro instruction identifies end-of -volume and end- of -data set 
conditions. For an end-of- volume condition, EOV causes switching of 
volumes and verification or creation of standard labels. For an 
end -of -data set condition, EOV causes your end-of -data set routine to be 
entered. When using XDAP, you issue EOV if switching of direct access 
volumes is necessary, or if secondary allocation is to be performed for 
a direct access data set opened for output. 

The only parameter of the EOV macro instruction is the address of the 
data control block of the data set. 

CLOSE — Restore Data Control Block 

The CLOSE macro instruction restores one or more data control blocks so 
that processing of their associated data sets can be terminated. You 
must issue CLOSE for all data sets that were used by the direct access 
channel program. Some of the procedures performed when CLOSE is 
executed are: 

• Release of data extent block (DEB) . 

• Removal of information transferred to data control block fields when 
OPEN was executed. 

• Verification or creation of standard labels. 

• Release of prog rammer- written appendage routines. 

The only parameter of the CLOSE macro instruction is the address of 
the data control block to be restored. (More than one data control 
block may be specified.) 

THE XDAP CONTROL BLOCK 

The three portions of the control block generated during execution of 
the XDAP macro instruction are described here. 

Event Control Block (ECB) 




The event control block begins on a full word boundary and occupies the 
first 4 bytes of the XDAP control block. Each time the direct access 
channel program terminates, the input/output supervisor places a 
completion code containing status information into the event control 
block (Figure XDAP1) . Before examining this information, you must test 
for the setting of the "Complete Bit" by issuing a WAIT macro 
instruction specifying the event control block. 

r t t T 

I WAIT Bit=0 j Complete Bit=l | Remainder of Completion Code | 

L JL J- J 

12 31 

Figure XDAP1. Event Control Block After Posting of Completion Code 

WAIT Bit 

A one bit in this position indicates that the WAIT macro 
instruction has been issued, but that the direct access channel 
program has not been completed. 

Complete Bit 

A one bit in this position indicates that the channel program has 
been completed; if it has not been completed, a zero bit is in this 
position. 
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Completion Code 

This code, which includes the WAIT and complete bits, may be one of 
the following 4-byte hexadecimal expressions: 



Code 
7F000000 

41000000 



Interpretation 
Direct access program has terminated without 
error . 

Direct access program has terminated with 
permanent error. 



42000000 



Direct access program has terminated because a 
direct access extent address has been violated. 



44000000 



Channel program has been intercepted because of 
permanent error associated with device end for 
previous request. You may reissue the 
intercepted request. 



48000000 



Request element for channel program has been 
made available after it has been purged. 



4B000000 



One of the following errors occurred during 
tape error recovery processing: 

• The CSW command address in the IOB is 
zeros. 

• An unexpected load point was encountered. 



4F000000 



Error recovery routines have been entered 
because of direct access error but are unable 
to read home address or record 0. 



50000000 



Channel program terminated with error. Input 
block was a DOS embedded checkpoint record. 



Input/Output Block (IOB) 

The input/output block is 40 bytes in length and immediately follows the 
event control block. The section "EXCP Macro Instruction" of this 
publication contains a diagram of the input/output block. The only 
fields with which the user of XDAP is concerned are the "First Two Sense 
Bytes" and "Channel Status Word" fields. You may wish to examine these 
fields when a unit check condition or an I/O interruption occurs. 



Direct Access Channel Program 

The direct access channel program is 24 bytes in length and immediately 
follows the input/output block. Depending on the type of I/O operation 
specified in the XDAP macro instruction, one of four channel programs 
may be generated. The three channel command words for each of the four 
possible channel programs are shown in Figure XDAP2. 
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T T 

Type of I/O Operation | CCW | Command Code 



h 


+_ 

Read by identification | 


1 

2 


1 
1 


Search ID Equal 
Transfer in Channel 




Verify by identification 1 ! 


3 


1 


Read Key and Data 


h 


f _ 




-+- 






Read by key | 


1 
2 


1 
1 


Search Key Equal 
Transfer in Channel 


1 


Verify by key 1 | 


3 


1 

-X- 


Read Data 


1 


T 


1 


T 
1 


Search ID Equal 


1 


Write by identification | 


2 
3 


1 

1 
-4~ 


Transfer in Channel 
Write Key and Data 


1 


T 


1 


T 
1 


Search Key Equal 




Write by key j 


2 
3 


1 
1 


Transfer in Channel 
Write Data 


1 


j_ 




_x 




1 


1 For verifying operations. 


the 


third CCW is flagged to suppress the 




transfer of information to 


mam 


storage. 



Figure XDAP2. The XDAP Channel Programs 
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CONVERSION OF RELATIVE TRACK ADDRESS TO ACTUAL ADDRESS 

To issue XDAP for device without the rotational position sensing feature 
(RPS) , you must provide the actual device address of the track 
containing the block to be processed. If you know only the relative 
track address, you can convert it to the actual address by using a 
resident system routine. The entry point to this conversion routine is 
labeled IECPCNVT. The address of the entry point is in the 
communication vector table (CVT). The address of the CVT is in location 
16. (The CVT macro instruction defines the symbolic names of all fields 
in the CVT. The macro definition and how to add it to the macro-library 
are in the Appendix of this chapter.) 

For devices without RPS, the conversion routine does all its work in 
general registers. You must load registers 0, 1, 2, 14, and 15 with 
input to the routine. Register usage is as follows: 



Register 




Use 
Must be loaded with a 4 -byte value of the form 
TTRN, where TT is the number of the track 
relative to the beginning of the data set, R is 
the identification of the block on that track, 
and N is the concatenation number of the data 
set. (0 indicates the first or only data set 
in the concatenation, 1 indicates the second, 
etc. ) 



Must be loaded with the address of the data 
extent block (DEB) of the data set. 

Must be loaded with the address of an 8-byte 
area that is to receive the actual address of 
the block to be processed. The converted 
address is of the form MBBCCHHR, where M 
indicates which extent entry in the data extent 
block is associated with the direct access 
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program (0 indicates the first extent, 1 
indicates the second, etc.); BB indicates the 
bin number of the direct access volume; CC 
indicates the cylinder address; HH indicates 
the actual track address; and R indicates the 
block identification- 

3-8 Are not used by the conversion routine. 

9-13 Are used by the conversion routine and are not 
restored. 

14 Must be loaded with the address to which 
control is to be returned after execution of 
the conversion routine. 

15 Is used by the conversion routine as a base 
register and must be loaded with the address at 
which the conversion routine is to receive 
control . 

CONVERSION OF RELATIVE SECTOR ADDRESS TO ACTUAL ADDRESS 

To issue XDAP for RPS devices, you must provide the actual device 
address of the sector containing the block to be processed. If you know 
only the relative sector address, you can convert it to the actual 
address by using a resident system routine. For RPS devices, the entry 
point to the conversion routine is labeled IECSCR01. The address of the 
entry point is in the CVT, and the address of the CVT is in location 16. 
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For RPS devices, the conversion routine does all its work in general 
registers. You must load registers 0, 1, 2, 14, and 15 with input to 
the routine. Register usage is as follows: 



Register 




Use 

For fixed length records, register must be 
loaded with a 4-byte value of the form DDKR, 
where DD is a 2 -byte field containing the 
physical block size, K is a 1-byte field 
containing the key length, and R is the record 
number with an unknown sector value. For 
variable length records, register must be 
loaded with a 4-byte value in the form of BBIR, 
where BB is a 2-byte field containing the total 
number of key and data bytes up. to, but not 
including the target record, I is a 1-byte 
field containing the record number with an 
unknown sector value. The high order bit of 
register must be turned on to indicate 
variable length records. 



3-8,12,13 
9-11 



Not used by the sector convert routine. 

Must be loaded with a 4 -byte field in which the 
first byte is the UCB device type code for the 
device (obtainable from UCB+19), and the 
remaining three bytes are the address of a 
1-byte area that is to receive the sector 
value. 

Not used . 

Used by the convert routine and are not saved 
or restored. 




14 



Must be loaded with the address to which 
control is to be returned after execution of 
the sector conversion routine. 



15 



Used by the conversion routine as a base 
register and must be loaded with the address of 
the entry point to the conversion routine. 



APPENDAGES 

For additional control over I/O operations, you may write appendages, 
which must be entered into the SVC library. Descriptions of these 
routines and their coding specifications are contained in the "EXCP 
Macro Instruction" section of this publication. 
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Appendix: CVT Macro Instruction 

If you want to use the CVT macro instruction, you must add the macro 
definition to the macro-library (SYSl.MACLIB) . This section contains 
the following: 

• The format of the CVT macro instruction. 

• The job control and utility statements needed to add the macro 
definition to the library. 

The fields in the communication vector table are described in the 
System Control Blocks publication. 

Format of the CVT Macro Instruction 

This macro instruction defines the symbolic names of all fields in 
the communication vector table (CVT). When coding this macro 
instruction, you must precede it with a DSECT statement. The format of 
the macro instruction is as follows: 

r t r 1 

| Name | Operation | Operand | 

j. + + 1 

| | CVT | I 

L I JL J 



Control Statements Required 

r 

j //jobname JOB {parameters} 

| //stepname EXEC PGM=IEBUPDTE,PARM=NEW 

//SYSPRINT DD SYSOUT=A 

//SYSUT2 DD DSNAME=SYSl.MACLIB,DISP=OLD 

//SYSIN DD * 

. / ADD NAME=CVT , LI ST=ALL 



CVT Macro definition 



./ ENDUP 
/* 
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Data Set Protection 



To use the data set protection feature of 
the operating system, you must create and 
maintain a password data set consisting of 
records that associate the names of the 
protected data sets with the password 
assigned to each data set- 



There are three ways to maintain the 
PASSWORD data set: 

• You can write your own routines. 

• You can use the PROTECT macro 
instruction. 

• You can use the utility control 
statements of the IEHPROGM utility 
program. 

This chapter is divided into two 
sections. The first section describes the 
general features of data set protection, 
including the use of your own routines to 
maintain the password data set. It 
provides the information you need to create 
the data set and characteristics of the 
data set. The second section discusses the 
PROTECT macro; it provides the programming 
information you need to use the macro and 
discusses the difference between using the 
PROTECT macro and using your own routines 
to maintain the password data set. 



RECOMMENDED PUBLICATIONS 

The IBM System/360 Operating System; Data 
Management Services publication (GC28-3746) 
contains a general description of the data 
set protection feature. 

The IBM System/360 Operating System: 
Messages and Codes publication (GC28-6631) 
contains a description of the operator 
messages and replies associated with the 
data set protection feature. 

The IBM System/360 Operating System: 
| Job Control Language Reference publication 
(GC28-6704) contains a description of the 
data definition (DD) statement parameter 
used to indicate that a data set is to be 
placed under protection. 

The IBM System/360 Operating System: 
Direct Access Device Space Management 
program logic manual, (GY28-6607) contains 
a description of the password data set 
record format. 
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The IBM System/360 Operating System; 
Utilities publication (GC28-6586) contains 
a description of how to maintain the 
PASSWORD data set using the utility 
statements of the IEHPROGM utility program, 
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Implementing Data Set Protection 

To prepare for use of the data set protection feature of the operating 
system, you place a sequential data set, named PASSWORD,, on the system 
residence volume (containing SYS1. NUCLEUS and SYS1.SVCLIB) - Note: If 
the routines that you write to maintain the password data set use the 
basic direct access method (BDAM), you must place a BDAM data set named 
PASSWORD on the system residence volume. This data set must contain one 
record for each data set placed under protection. In turn, each record 
contains a data set name, the password for that data set, a counter 
field, a protection mode indicator, and a field for recording any 
information you desire to log. On the system residence volume, these 
records are formatted as a "key area" (data set name and password) and a 
"data area" (counter field, protection mode indicator, and logging 
field). The data set is searched on the "key area." 

You can write routines to create and maintain the PASSWORD data set. 
(If you use the PROTECT macro instruction to maintain the password data 
set, see the section in this chapter called USING THE PROTECT MACRO 
INSTRUCTION TO MAINTAIN THE PASSWORD DATA SET. If you use the IEHPROGM 
utility program to maintain the PASSWORD data set, see the publication 
IBM System/360 Operating System: Utilities , GC28-6586.) These routines 
may be placed in your own library or the system* s linkage editor library 
(SYS1.LINKLIB) . You may use a data management access method or EXCP 
programming to handle the PASSWORD data set. 

If a data set is to be placed under protection, it must have a 
protection indicator set in its label (DSCB or header 1 tape label). 
This is done by the operating system when the data set is created or by 
the IEHPROGM utility program. The protection indicator is set in 
response to an entry in the LABEL= parameter of the DD statement 
associated with the data set being placed under protection. The Job 
Control Language Reference publication describes the entry. Note : Data 
sets on magnetic tape are protected only when standard labels are used. 

Users who wish to have the password supplied by some method other 
than operator key-in may replace the password reading module with their 
own routine. The READPSWD source module may be used as a base for 
writing a new module. In this case, the new object module replaces 
module READPSWD on the SVCLIB. 

The balance of this chapter discusses the PASSWORD data set 
characteristics, the creation of protected data sets, and operating 
characteristics of the data set protection feature. 



| Password Data Set Characteristics 

The PASSWORD data set must reside on the same volume as your operating 
system. The space you allocate to the PASSWORD data set must be 
contiguous, i.e., its DSCB must indicate only one extent. The amount of 
space you allocate is dependent on the number of data sets your 
installation desires to place under protection. Each entry in the 
PASSWORD data set requires 132 bytes of space. The organization of the 
PASSWORD data set is physical sequential, the record format is 
unblocked, fixed length records (RECFM=F). These records are 80 bytes 
long (LRECL=80) and form the data area of the PASSWORD data set records 
on direct access storage. In these direct access storage records, the 
data area is preceded by a key area of 52 bytes (KEYLEN=52). The 
password assigned may be from one to eight alphameric characters. The 
IBM System/360 Operating System Direct Access Device Space Management 
program logic manual (GY28-6607) describes the password data set record 
format. 
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Protecting the Password Data Set 

You protect the PASSWORD data set itself by creating a password record 
for it when your program initially builds the data set. Thereafter, the 
PASSWORD data set cannot be opened (except by the operating system 
routines that scan the data set) unless the operator enters the 
password. 

Note ; If a problem occurs on a pas sword- protected system data set, 
maintenance personnel must be provided with the password in order to 
access the data set and resolve the problem. 



Creating Protected Data Sets 

A data definition (DD) statement parameter (LABEL=) is used to indicate 
that a data set is to be placed under protection. You may create a data 
set, and set the protection indicator in its label, without entering a 
password record for it in the PASSWORD data set. However, once the data 
set is closed, any subsequent opening results in termination of the 
program attempting to open the data set, unless the password record is 
available and the operator can honor the request for the password. 
Operating procedures at your installation must ensure that password 
records for all data sets currently under protection are entered in the 
PASSWORD data set. 

Protection Feature Operating Characteristics 

This section provides information concerning actions of the protection 
feature in relation to termination of processing, volume switching, data 
set concatenation, SCRATCH and RENAME functions, and counter 
maintenance. 

Termination of Processing 

Processing is terminated when: 

1. The operator cannot supply the correct password for the protected 
| data set being opened after two tries. 

2. A password record does not exist in the PASSWORD data set for the 
protected data set being opened. 

3. The protection mode indicator setting in the password record, and 
the method of I/O processing specified in the open routine do not 
agree, e.g., OUTPUT specified against a read-only protection mode 
indicator setting. 

4. There is a mismatch in data set names for a data set involved in a 
volume switching operation. This is discussed in the next section. 

Volume Switching 

The operating system end- of- volume routine does not request a password 
for a data set involved in a volume switch. Continuity of protection is 
handled in the following ways: 

Input Data Sets - Tape and Direct Access Devices 

Processing continues if there is an equal comparison between the 
data set name in the tape label or DSCB on .he volume switched to, 
and the name of the data set opened with the password. An unequal 
comparison terminates processing. 
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Output Data Sets - Tape Devices 

The protection indicator in the tape label on the volume switched to 

is tested: 

1. If the protection indicator is set ON, an equal comparison 
between the data set name in the label and the name of the data 
set opened with the password allows processing to continue. An 
unequal comparison results in a call for another volume. 

2. If the protection indicator is OFF, processing continues, and a 
new label is written with the protection indicator set ON. 

3. If only a volume label exists on the volume switched to, 
processing continues, and a new label is written with the 
protection indicator set on. 

Output Data Sets - Direct Access Devices 

For existing data sets, an equal comparison between the data set 
name in a DSCB on the volume switched to, and the name of the data 
set opened with the password allows processing to continue. For new 
output data sets, the mechanism used to effect volume switching 
ensures continuity of protection and the DSCB created on the new 
volume will indicate protection. 

Data Set Concatenation 

A password is requested for every protected data set that is involved in 
a concatenation of data sets, regardless of whether the other data sets 
involved are protected or not. 

SCRATCH and RENAME Functions 

An attempt to perform the SCRATCH or RENAME functions on a protected 
data set results in a request for the password. The protection feature 
issues an operator's message (IEC301A) when a protected data set is the 
object of these functions. The Messages and Codes publication discusses 
the message. 

Counter Maintenance 

The operating system does not maintain the counter in the password 
record and no overflow indication will be given (overflow after 65,535 
openings). You must provide a counter maintenance routine to check and, 
if necessary, reset this counter. 

Using the Protect Macro Instruction to Maintain the Password Data Set 

I To use the PROTECT macro instruction, your password data set must be on 
the system residence volume. The PROTECT macro can be used to: 

• Add an entry to the password data set. 

• Replace an entry in the password data set. 

• Delete an entry from the password data set. 

• Provide a list of information about an entry in the password data 
set; this list will contain the security counter, access type, and 
the 77 bytes of security information in the "data area" of the 
entry. 

In addition, the PROTECT macro, will update the DSCB of the protected 
data set, for a direct access device, to reflect its protected status; 
this feature eliminates the need for you to use job control language 
whenever you place a data set under protection. 
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PASSWORD DATA SET CHARACTERISTICS AND RECORD FORMAT WHEN YOU USE THE 
PROTECT MACRO 

When you use the PROTECT macro, the record format and characteristics of 
the password data set should be the same as the record format and 
characteristics when you use your own routines to maintain it # with two 
exceptions: the number of records that you establish for each protected 
data set and the values of the protection mode indicator. 

Number of Records for Each Protected Data Set : When you use the PROTECT 
macro, the password data set must contain at least one record for each 
protected data set. The password (the last 8 bytes of the "key area") 
that you assign when you place the data set under protection for the 
first time is called the control password, in addition, you may create 
as many secondary records for the same protected data set as you need. 
The passwords assigned to these additional records are called secondary 
passwords. This feature is helpful if you want several users to have 
access to the same protected data set, but you also want to control the 
manner in which they can use it. For example: one user could be 
assigned a password that allowed the data set to be read and written, 
and another user could be assigned a password that allowed the data set 
to be read only. 

Note : The PROTECT macro will update the DSCB of the protected data set 
only when you issue it for adding, replacing or deleting a control 
password. 

Protection Mode Indicator : You can set the protection mode indicator in 
the password record to four different values: 

• X'OO 1 to indicate that the password is a secondary password and the 
protected data set is to be read only. 

• X'SO* to indicate that the password is the control password and the 
protected data set is to be read only. 

• X'Ol* to indicate that the password is a secondary password and the 
protected data set is to be read and written. 

• X'Sl* to indicate the password is the control password and the 
protected data set is to be read and written. 

Since the DSCB of the protected data set is updated only when the 
control password is changed, it is possible to request protection 
attributes for secondary passwords which conflict with the protection 
attributes of the control password. 

If the control password has read only protection, its secondary 
passwords may have read only or read write protection. A request for a 
secondary password with read without password protection will result in 
a secondary password with read write protection. A read only control 
password may be changed to a read write control password without 
affecting any secondary passwords, but if a read only control password 
is changed to a read without password control password all secondary 
passwords will automatically become read without password secondary 
passwords. 

If the control password has read write protection, its secondary 
passwords may have read only or read write protection. A request for a 
secondary password with read without password protection will result in 
a secondary password with read write protection. A read write control 
password may be changed to a read only control password without 
affecting any secondary passwords, but if a read write control password 
is changed to a read without password control password all secondary 
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passwords will automatically become read without password secondary 
passwords. 

If the control password has read without password protection, its 
secondary passwords must also have read without password protection. A 
request for a read only or for a read write secondary password will 
result in a read without password secondary password. If a read without 
password control password is changed to either a read only or read write 
control password all its secondary passwords will automatically become 
read write secondary passwords. 



PROGRAMMING CONVENTIONS FOR THE PROTECT MACRO INSTRUCTION 
The format of the PROTECT macro is: 



r t t 

| Name |Operation| Operand 

|. + + _ 

| [symbol] | PROTECT U(l) register 1: address of a parameter list 

j (optional) | |<(REG) any register: address of a parameter listj>| 

I | | (list addr address of the parameter list 

L X L j 



J 



When you issue the PROTECT macro, you should have already established 
the parameter list. Its size and contents depend on the function that 
you want the macro to perform. In any case, the first byte of the 
parameter list is an entry code that indicates the function: 

• X'Ol* for adding an entry to the parameter list. 

• X , 02 f for replacing an entry in the parameter list. 

• X*03* for deleting an entry from the parameter list. 

• X'OU' for listing the information in a password data set entry. For 
a complete discussion of the contents of the parameter lists, see 
figures PSWD1 to PSWD4 and the notes explaining each of these 
figures. 

PROTECT Macro Parameter Lists 




The parameter lists, their formats and contents are; 






X'OT 


1 00 00 00 


4 


Data Set Length 


5 


Pointer to Data Set Name 


8 


00 


9 


00 00 00 


12 


00 


13 


Pointer to Control Password 


16 


Number of Volumes 


17 


Pointer to Volume List 


20 


Protection Code 


21 


Pointer to New Password 


24 


String Length 


25 


Pointer to String 



Figure PSWD1. Parameter List for Add Function 
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Explanatory Notes for Figure PSWD1. 

X'Ol* 

Entry code indicating add function. 

13 Pointer to control password. 

The control password is the password assigned when the data set was 
placed under protection for the first time. This can be a string of 
zeros if the new password is the control password. 

16 Number of volumes. 

If the data set is not cataloged and you want to have it flagged as 
protected, you have to specify the number of volumes in this field. 
A zero indicates that the catalog information should be used. 

17 Pointer to volume list. 

If the data set is not cataloged and you want to have it flagged as 
protected, you provide the address of a list of volume serial 
numbers in this field. Zeros indicate that the catalog information 
should be used. 

20 Protection code. 

A one-byte number indicating the type of protection: X'00* 
indicates default protection (for the add function, the default 
protection is the type of protection specified in the control 
password record of the data set), X'Ol* indicates that the data set 
is to be read and written, X'02' indicates that the data set is to 
be read only and X*03* indicates that the data set can be read 
without a password, but a password is needed to write into it. The 
PROTECT macro will use the protection code value, specified in the 
parameter list, to set the protection mode indicator in the password 
record. 

21 Pointer to new password. 

If the data set is being placed under protection for the first time, 
the new password is the same as the control password. If you are 
adding a secondary entry, the new password is different from the 
control password. 

24 String length. 

The length of the character string (maximum 77 bytes) that you want 
to place in the optional information field of the password record. 
If you do not want to add information, set this field to zero. 

25 Pointer to string. 

The address of the character string that is going to be put in the 
optional information field. If you do not want to add additional 
information, set this field to zero. 
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X'02' 


00 00 00 


4 


Data Set Length 


5 


Pointer to Data Set Name 


8 


00 


9 


Pointer to Current Password 


12 


00 


13 


Pointer to Control Password 


16 


Number of Volumes 


17 


Pointer to Volume List 


20 


Protection Code 


21 


Pointer to New Password 


24 


String Length 


25 


Pointer to String 



Figure PSWD2. Parameter List for Replace Function 

Explanatory Notes for Figure PSWD2. 

X'02 1 

Entry code indicating REPLACE function 

9 Pointer to current password. 

The address of the password that is going to be replaced. 



13 Pointer to control password. 

The address of the password assigned to the data set when it was 
first placed under protection. This can be zero if the current 
password is the control password. 

16 Number of volumes. 

If the data set is not cataloged and you want to have it flagged as 
protected, you have to specify the number of volumes in this field. 
A zero indicates that the catalog information should be used. 

17 Pointer to volume list. 

If the data set is not cataloged and you want to have it flagged as 
protected, you have to provide the address of a list of volume 
serial numbers in this field. If this field is zero, the catalog 
information will be used. 

20 Protection code. 

A one-byte number indicating the type of protection: X'OO* 
indicates that the protection is default protection (for the 
replacef unction the default protection is the protection specified 
in the current password record of the data set), X'Ol* indicates 
that the data set is to be read and written, X , 02 l indicates that 
the data set is to be read only, and X'OS 1 indicates that the data 
set can be read without a password, but a password is needed to 
write into the data set. 

21 Pointer to new password. 

The address of the password that you want to replace the current 
password. 

24 String length. 

The length of the character string (maximum 77 bytes) that you want 
to place in the optional information field of the password record. 
Set to zero if you do not want to add additional information. 

25 Pointer to string. 

The address of the character string that is going to be put in the 
optional information field of the password record. Set the address 
to zero if you do not want to add additional information. 
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X'03' 


1 

00 00 00 


4 

Data Set Length 


5 

Pointer to Data Set Name 


8 


9 


Pointer to Current Password 


12 

00 


13 


Pointer to Control Password 


16 


Number of Volumes 


17 


Pointer to Volume List 



Figure PSWD3. Parameter List for Delete Function 



Explanatory Notes for Figure PSWD3. 

X'OS*. 

Entry code indicating delete function. 

9 Pointer to current password. 

The address of the password that you want to delete. You can delete 
either a control entry or a secondary entry. 

13 Pointer to control password. 

The address of the password assigned to the data set when it was 
placed under protection for the first time. This can be zeros if 
the current password is also the control password. 

16 Number of volumes. 

If the data set is not cataloged and you want to have it flagged as 
protected, you have to specify the number of volumes in this field. 
A zero indicates that the catalog information should be used. 

17 Pointer to volume list. 

If the data set is not cataloged and you want to have it flagged as 
protected, you have to provide the address of a list of volume 
serial numbers in this field. If this field is zero, the catalog 
information will be used. 






X'04' 


1 


Address of 80 Byte Buffer 


4 

Data Set Length 


5 

Address of Data Set Name 


8 00 


9 


Address of Current Password 



Figure PSWD4. Parameter List for List Function 



Explanatory notes for using Figure PSWD4. 

X'04 f . 

Entry code indicating list function. 

1 Address of 80- byte buffer. 

The address of a buffer where the list of information can be 
returned to your program by the macro instruction. 

| 9 Pointer to current password. 

The address of the password of the record that you want listed. 
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Return Codes from the PROTECT Macro 



When the PROTECT macro finished processing, register 15 will contain a 
return code that indicates what happened during the processing. Figure 
PSWD5 contains the return codes and their explanations. 



| Register 15 | 



Explanation 




The updating of the password data set was successfully 

completed. 

The password of the data set name was already in the 

password data set. 

The password of the data set name was not in the password 

data set. 

A control password is required or the one supplied is 

incorrect. 

The supplied parameter list was incomplete or incorrect. 

There was an I/O error in the password data set. 

The password data set was full. 

The validity check of the buffer address failed. 

The LOCATE macro failed. LOCATE* s return code is in 

register 1 and the number of indexes searched is in 

register 0. 

The OBTAIN macro failed. OBTAIN* s return code is in 

register 1. 

The DSCB could not be updated. 

The password data set does not exist. 

Tape data set can not be protected. 

Data set in use. 



♦For these return codes, the password data set has been updated, but 
the DSCB has not been flagged to indicate the protected status of the 
data set . 

**For this return code, a message is written to the console indicating 
that the password data set is full. 

L 

Figure PSWD5. Return Codes from the PROTECT Macro 



-* 
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System Macro Instructions 



This chapter contains the description and 
formats of macro instructions that allow 
you either to modify control blocks or to 
obtain information from control blocks and 
system tables. Before reading this 
chapter, you should be familiar with the 
information contained in the prerequisite 
publications listed below. 



PREREQUISITE PUBLICATIONS 

The IBM System/360 Operating System; 
Assembler Language publication (GC28-6514) 
contains the information necessary to code 
programs in the assembler language. 

The IBM System/360 Operating System; 
System Control Blocks publication 
(GC2 8-6628) contains format and field 
descriptions of the system control blocks 
referred to in this chapter. 
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SYSTEM MACRO INSTRUCTIONS IN THIS PUBLICATION 

The following system macro instructions are described in the chapters of this publication 
that deal with the subjects shown. 



Macro 




Macro 


Instruction 


Chapter Subject 


Instruction 


ATLAS 


EXCP Macro Instruction 


LOCATE 


CAMLST 


VTOC Maintenance 


OBTAIN 


CATALOG 


Catalog Maintenance 


OPEN 


CLOSE 


EXCP Macro Instruction 


. . . # TYPE=J 


CVT 


XDAP Macro Instruction 






(Appendix) 


POST, WAIT (Ei 


DCB 


EXCP Macro Instructions 


PURGE 


DEVTYPE 


System Macro Instructions 




EOV 


EXCP Macro Instruction 


RDJFCB 


EXCP 


EXCP Macro Instruction 


RENAME 


IECDSECT, 


IECDSECT, IEFJFCBN, 




IEFJFCBN, 


IEFUCBOB Macro 


RESTORE 


IEFUCBOB 


Instructions 





INDEX 



| LABEL 



Catalog Maintenance SCRATCH 



System Macro Instructions XDAP 



Chapter Subject 

Catalog Maintenance 

Catalog Maintenance 

EXCP Macro Instruction 

System Macro Instructions 
(Read a JFCB) 

EXCP Macro Instruction, 
XDAP Macro Instruction 

EXCP Macro Instruction 
(Appendix) 

System Macro Instructions 

VTOC Maintenance, 
Data Set Protection 

EXCP Macro Instruction 
(Appendix) 

VTOC Maintenance, 
Data Set Protection 

XDAP Macro Instruction 
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Locate Device Characteristics (DEVTYPE) Macro Instruction 

The DEVTYPE macro instruction is used to request information relating to 
the characteristics of an I/O device, and to cause this information to 
be placed into a specified area. (The results of a DEVTYPE macro 
instruction executed before a checkpoint is taken should not be 
considered valid after a checkpoint/restart occurs.) 

r t — • t ' T 

I Name | Operation | Operand | 

,. + + 1 

| [symbol] | DEVTYPE j ddloc-addrx,area-addrx [,DEVTAB] [,RPS] | 

L ± X J 

ddloc-addrx 

specifies the address of a doubleword that contains the symbolic 
name of the DD statement to which the device is assigned. The name 
must be left justified in the doubleword, and must be followed by 
blanks if the name is less than eight characters. The doubleword 
need not be on a doubleword boundary. 

area-addrx 

specifies the address of an area into which the device information 
is to be placed. The area can be two, five, or six full words, 
depending on whether or not the DEVTAB and RPS operands are 
specified. The area must be on a fullword boundary. 

DEVTAB 

If DEVTAB is specified, and the device is a direct access device, 
five full words of information are placed into your area. If 
DEVTAB is specified, and the device is not a direct access device, 
two fullwords of information are placed into your area. If DEVTAB 
is not specified, two fullwords of information are placed into your 
area. 

RPS 

If RPS is specified, DEVTAB must also be specified. The RPS 
parameter causes one additional full word of RPS information to be 
included with the DEVTAB information. 

Note : Any reference to a dummy DD statement in the DEVTYPE macro 
instruction will cause zeroes to be placed in the output area. 

Device Characteristics Information 

The following information is placed into your area: 

Word 1 Device code from the UCB in which: 

Byte 1 bit Unas signed 

bit 1 Overrunable device 1 = yes 
bit 2 Burst/byte mode 1 = burst 
bit 3 Data chaining 1 = yes 
bit U -7 Model code 

Byte 2 Optional features 

Byte 3 Device classes 

Byte 4 Unit type 

Note : Bit settings for byte 2 are noted in the UCB format and field 
description in the System Control Blocks publication. 
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Word 2 Maximum block size. For direct access devices, this 

value is the maximum size of an unkeyed block; for 
magnetic or paper tape devices, this value is the 
maximum block size allowed by the operating system. 
For all other devices, this value is the maximum 
block size accepted by the device. 

If DEVTAB is specified, the next three full words contain the 
following information: 



Word 3 



Word 4 



Word 5 



Bytes 1-2 The number of physical cylinders on the 
device. 

Bytes 3-4 The number of tracks per cylinder. 

Bytes 1-2 Maximum track length. Note that for the 
2305 and 3330 direct access devices this 
value is not equal to the value in word 
two (maximum block size) as it is for 
other IBM direct access devices. 

Byte 3 Block overhead - the number of bytes 

required for gaps and check bits for each 
keyed block other than the last block on a 
track. 

Byte 4 Block overhead - the number of bytes 

required for gaps and check bits for a 
keyed block that is the last block on a 
track. 

Byte 1 Block overhead - the number of bytes to be 
subtracted if a block is not keyed. 

Byte 2 bits 0-6 Reserved (except for the 2321 on 

which has a 1 in bit 6 ) . 

bit 7 If 1, a tolerance factor must be 
applied to all blocks except the 
last block on the track. 

Bytes 3-4 Tolerance factor - this factor is used to 
calculate the effective length of a block. 
The calculation should be performed as 
follows: 

Step 1 - add the block's key length to the 

block's data length. 

Step 2 - test bit 7 of byte 2 of word 5. 

If bit 7 is 0, perform step 3. If bit 7 

is 1, multiply the sum computed in step 1 

by the tolerance factor. Shift the result 

of the multiplication nine bits to the 

right. 

Step 3 - add the appropriate block 

overhead to the value obtained above. 



If DEVTAB and RPS are specified, the next full word contains the 
following information: 



Word 6 



Bytes 1-2 R0 overhead for sector calculations 
Byte 3 Number of sectors for the device. 

Byte 4 Number of data sectors for the device. 
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Output for Each Device Type 



Maximum 
UCB Type Field Record Size 
(Word 1, (Word 2, 
In Hexadecimal) In Decimal) 



2540 
2540 
2540 
2540 


Reader 
Reader w/CI 
Punch 
Punch w/CI 




10 
10 
10 
10 


00 
01 
00 
01 


08 
08 
08 
08 


01 
01 
02 
02 


80 
80 
80 
80 


1442 
1442 
1442 
1442 


Reader-Punch 
Reader-Punch 
Serial Punch 
Serial Punch 


w/CI 
w/CI 


50 
50 
51 
51 


00 
01 
80 
01 


08 
08 
08 
08 


03 
03 
03 
03 


80 
80 
80 
80 


2501 
2501 


Reader 
Reader w/CI 




50 
50 


00 
01 


08 
08 


04 
04 


80 
80 


2520 
2520 
2520 
2520 


Reader Punch 
Reader Punch 
B2-B3 
B2-B3 w/CI 


w/CI 


50 
50 
11 
11 


00 
01 
00 
01 


08 
08 
08 
08 


05 
05 
05 
05 


80 
80 
80 
80 


1403 
1403 


w/UCS 




10 
10 


00 
80 


08 
08 


08 
08 


120* 
120* 


1404 






10 


00 


08 


08 


120* 


1443 






10 


00 


08 


0A 


120* 


3211 






10 


80 


08 


09 


132* 


2671 






10 


00 


08 


10 


32767 


1052 






10 


00 


08 


20 


130 


2400 
2400 
2400 
2400 
2400 


(9-track) 
(9 -track, p. e 
(9-track, A.6 
(7-track) 
(7-track, d.c 


.) 

1.) 

.) 


30 
34 
34 
30 
30 


00 
00 
20 
80 
CO 


80 
80 
80 
80 
80 


01 
01 
01 
01 
01 


32767 
32767 
32767 
32767 
32767 


2301 






30 


40 


20 


02 


204 83 


230 2 






30 


00 


20 


04 


4984 


230 3 






30 


00 


20 


03 


4892 


2311 






30 


00 


20 


01 


3625 


2314 






30 


CO 


20 


08 


72 94 


2321 






30 


00 


20 


05 


2000 


3210 
3215 


Printer Keyboard 
Printer Keyboard 


10 
10 


00 
00 


08 
08 


22 
23 


130 
130 


3505 
3505 
3525 
3525 


Reader 
Reader w/CI 
Punch 
Punch w/CI 




10 
10 
10 
10 


00 
01 
00 
01 


08 
08 
08 
08 


06 
06 
OC 
OC 


80 
80/160 

80 
80/160 


2305- 


-1 




30 


50 


20 


06 


14,138 


230 5- 


-2 




30 


50 


20 


07 


14,660 


| 3330 






30 


50 


20 


09 


13,030 



DEVTAB 

(Words 3, 4, and 5, 
In Hexadecimal) 
Not Applicable 
Not Applicable 
Not Applicable 
Not Applicable 

Not Applicable 
Not Applicable 
Not Applicable 
Not Applicable 

Not Applicable 
Not Applicable 

Not Applicable 
Not Applicable 
Not Applicable 
Not Applicable 

Not Applicable 
Not Applicable 

Not Applicable 

Not Applicable 

Not Applicable 

Not Applicable 

Not Applicable 

Not Applicable 
Not Applicable 
Not Applicable 
Not Applicable 
Not Applicable 

000100C85003BA35350002 00 

00FA002E1378511414010219 

0050 000A131C922626000200 

0OCBO00AOE29511414010219 

00CB00141C7E922D2D010216 

140A051407D06 41010030219 

Not Applicable 
Not Applicable 

Not Applicable 
Not Applicable 
Not Applicable 
Not Applicable 

003000 838E8 02 7 8CA0 9020 

006A00 83A0A01215B0902 00 

019B0013336DBFBF380 10200 



RPS 

(Word 6 

In Hexadecimal) 

Not Applicable 

Not Applicable 

Not Applicable 

Not Applicable 

Not Applicable 
Not Applicable 
Not Applicable 
Not Applicable 

Not Applicable 
Not Applicable 

Not Applicable 
Not Applicable 
Not Applicable 
Not Applicable 

Not Applicable 
Not Applicable 

Not Applicable 

Not Applicable 

Not Applicable 

Not Applicable 

Not Applicable 

Not Applicable 
Not Applicable 
Not Applicable 
Not Applicable 
Not Applicable 

Not Applicable 

Not Applicable 

Not Applicable 

Not Applicable 

Not Applicable 

Not Applicable 

Not Applicable 
Not Applicable 

Not Applicable 
Not Applicable 
Not Applicable 
Not Applicable 

02985A57 

0140B4B1 

00ED807C 
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Device 



1053 






14 


00 


10 


04 


2250 


(Mod 


1) 


31 


XX 


10 


02 


2250 


(Mod 


2) 


32 


XX 


10 


02 


2250 


(Mod 


3) 


33 


XX 


10 


02 


2280 






30 


00 


10 


05 


2282 






30 


00 


10 


06 



3066 (Model 165 

System Console) 10 00 10 08 



Maximum 
UCB Type Field Record Size DEVTAB 
(Word 1, (Word 2, (Words 3, 4, and 5, 
In Hexa deci mal) In Decimal) In Hexadecimal) 

Not Applicable 



Not Applicable 
Not Applicable 
Not Applicable 

Not Applicable 

Not Applicable 

Not Applicable 



RPS 

(Word 6 

In Hexadecimal) 

Not Applicable 

Not Applicable 
Not Applicable 
Not Applicable 

Not Applicable 

Not Applicable 

Not Applicable 



5450 (Model 85 
Operators 
Console) 


10 


00 


10 


07 




Not 


Applicable 


3400 (9-track,p.e.) 
3400 (9-track, d.d.) 
3400 (7-track) 


34 
34 
34 


00 
20 
CO 


80 
80 
80 


03 
03 
03 


32767 
32767 
32767 


Not 
Not 
Not 


Applicable 
Applicable 
Applicable 


Leqend 

















Cl-Card image feature, d. c.-data conversion, d.d. -dual density, 
p. e. -phase encoding, UCS-universal character set, w/-with 

♦Although certain models can have a larger line size, the minimum 
line size is assumed. 

xx = Special feature (byte 2) configurations may be obtained from 
the System Control Blocks publication. 



Communication Equipment 

1030, 1050, 83B3, TWX, 2250, S360 

1060, 115A, 1130 

2780 

2740 

Y=Adapter Type (Bits 0-3) 
Hex Value Meaning 



UCB Type Field 

51xx4 0YZ 
52xx4 0YZ 
53xx4 0YZ 
54xx4 0YZ 



Record Size 

Not Applicable 
Not Applicable 
Not Applicable 
Not Applicable 



Z=Control Unit (Bits 4-7) 



1 IBM Terminal Adapter, Type I 

2 IBM Terminal Adapter, Type II 

3 IBM Telegraph Adapter 

4 Telegraph Adapter, Type I 

5 Telegraph Adapter, Type II 

6 World Trade Telegraph Adapter 

7 Synchronous Adapter, Type I 

8 IBM Terminal Adapter, Type III 

9 Synchronous Adapter, Type II 



Hex value 

1 
2 
3 



Meaning 
2702 
2701 
2703 



Not Applicable 

Not Applicable 
Not Applicable 
Not Applicable 



Exceptional Returns 

The following return codes are placed in register 15: 

00 - Request completed satisfactorily. 

04 - Ddname not found. 

08 - Invalid area address. The address of the output area either 

violates protection, or it is out of the range of main storage. 
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How to Read a Job File Control Block 

To accomplish the functions that are performed as a result of an OPEN 
macro instruction, the OPEN routine requires access to information that 
you have supplied in a data definition (DD) statement. This information 
is stored by the system in a job file control block (JFCB) . 

Usually, the programmer is not concerned with the JFCB itself- In 
special applications, however, you may find it necessary to modify the 
contents of a JFCB before issuing an OPEN macro instruction. To assist 
you, the system provides the RDJFCB macro instruction- This macro 
instruction causes a specified JFCB to be read into main storage from 
the job queue in which it has been stored. Format and field description 
of the JFCB is contained in the System Control Blocks publication. 

When subsequently issuing the OPEN macro instruction, you must 
indicate, by specifying the TYPE=J option, that you have supplied a 
modified JFCB to be used during the initialization process. 

The JFCB Is returned to the job queue by the OPEN routine or the 
OPENJ routine, if any of the modifications in the following list occur. 
These modifications can occur only if the information is not originally 
in the JFCB. 

• Expiration date field and creation date field merged into the JFCB 
from the DSCB. 

• Secondary quantity field merged into the JFCB from the DSCB. 

• DCB fields merged into the JFCB from the DSCB. 

• DCB fields merged into the JFCB from the DCB. 

• Volume serial number fields added to the JFCB. 

• Data set sequence number field added to the JFCB. 

• Number of volumes field added to the JFCB. 

If you make these, or any other modifications, and you want the JFCB 
returned to the job queue, you must set the high-order bit of field 
JFCBMASK+4 to one. This field is in the JFCB. Setting the high-order 
bit of field JFCBMASK+4 to zero does not necessarily suppress the return 
of the JFCB to the job queue. If the OPEN or OPENJ routines have made 
any of the above modifications, the JFCB is returned to the job queue. 
To inhibit writing the JFCB back to the job queue during an OPENJ, the 
field JFCBTSDM should be set to X'OS* prior to issuing the OPEN macro. 



OPEN — PREPARE THE DATA CONTROL BLOCK FOR PROCESSING (S) 

The OPEN macro instruction initializes one or more data control blocks 
so that their associated data sets can be processed. 

A full explanation of the operands of the OPEN macro instruction, 
| except for the TYPE=J option, is contained in the Data Management Macro 
Instructions publication. The TYPE=J option, because it is used in 
conjunction with modifying a JFCB, should be used only by the system 
programmer or only under his supervision. 

System Macro Instructions 115 




r t t 1 

| Name | Operation! Operand | 

j. + + j 

| [symbol] | OPEN J ( {dcb-addr, [ (opt^-code [,opt 2 -code] ) ] , }. . . ) | 
I j J [,TYPE=J] J 

L J. A ; J 

TYPE=J 

specifies that, for each data control block referred to, the 
programmer has supplied a job file control block (JFCB) to be used 
during initialization. A JFCB is an internal representation of 
information in a DD control statement. 

During initialization of a data control block, its associated JFCB 
may be modified with information from the data control block or an 
existing data set label or with system control information. 

The system always creates a job file control block for each DD 
control statement. The job file control block is placed in a job 
queue on direct access storage. Its position, in relation to other 
JFCBs created for the same job step, is noted in a main storage 
table. 

When this operand is specified, the user must also supply a DD 
control statement. However, the amount of information given in the 
DD statement is at the programmer's discretion, because he can 
ignore the system- created job file control block. (See the 
examples of the RDJFCB macro instruction for a technique for 
modification of a system-created JFCB.) 

Caution ; In MVT configurations of the operating system, data set 
integrity provided by the job scheduler functions is lost if you change, 
or do not use, the DSNAME=parameter in the DD statement. 

Note : The DD statement must specify at least: 

• Device allocation (refer to the Job Control Language publication for 
methods of preventing share status) . 

• A ddname corresponding to the associated data control block DCBDDNAM 
field. 

RDJFCB — READ A JOB FILE CONTROL BLOCK (S) 

The RDJFCB macro instruction causes a job file control block (JFCB) to 
be read from the job queue into main storage for each data control block 
specified. 

r t t ■ 1 

| Name | Operation| Operand | 

j. + + j 

| [symbol] | RDJFCB | ( {dcb-addr, [ (opt^-c ode [, opt 2 -code] )],}... ) | 

L J. .± J 



deb , (opt ± , opt 2 ) 

(same as deb, opt^., and opt 2 operands in OPEN macro instruction) 

Although the opt^ and opt 2 operands are not meaningful during the 
execution of the RDJFCB macro instruction, these operands can 
appear in the L-form of either the RDJFCB or OPEN macro instruction 
to generate identical parameter lists, which can be referred to 
with the E-form of either macro instruction. 
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Examples : The macro instruction in EX1 creates a parameter list for two 
data control blocks: INVEN and MASTER. In creating the list, both data 
control blocks are assumed to be opened for input; opt 2 for both blocks 
is assumed to be DISP. The macro instruction in EX2 reads the system- 
created JFCBs for INVEN and MASTER from the job queue into main storage, 
thus making the JFCBs available to the problem program for modification. 
The macro instruction in EX3 modifies the parameter list entry for the 
data control block named INVEN and indicates, through the TYPE=J 
operand, that the problem program is supplying the JFCBs for system use. 



EX1 RDJFCB (INVEN, , MASTER ) ,MF=L 



EX2 RDJFCB MF=(E,EX1) 



EX3 OPEN (, (RDBACK,LEAVE)),TYPE=J,MF=(E,EX1) 



Programming Notes 

Any number of data control block addresses and associated options may be 
specified in the RDJFCB macro instruction. This facility makes it 
possible to read job file control blocks in parallel. 

An exit list address must be provided in each data control block 
specified by an RDJFCB macro instruction. Each exit list must contain 
an active entry that specifies the main storage address of the area into 
which a JFCB is to be placed. A full discussion of the exit list and 
its use is contained in the Data Management Services publication. The 
format of the job file control block exit list entry is as follows: 



r t T" 

Type of Exit | Hexadecimal Code | 

List Entry | (high- order byte) j 



Contents of Exit List Entry 
(three low-order bytes) 



Job file j 

control blockj 



07 



j Address of a 176-byte area to be 
j provided if the RDJFCB or OPEN 
| (TYPE=J) macro instruction is used, 
j This area must begin on a fullword 
| boundary and must be located 
j within the user's region. 




The main storage area into which the JFCB is read must be at least 
176 bytes long. 



The data control block may be open or closed when this macro 
instruction is executed. 

If the JFCB is read successfully for all DCBs in the parameter list, 
a return code of zero is placed in register 15. If the JFCB is not read 
for any of the DCBs because the DDNAME is blank or a DD statement is not 
provided, then a return code of 4 is placed in register 15. 



Cautions : The following errors cause the results indicated: 
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Error 

A DD control statement has not been 

provided. 

DDNAME field in DCB is blank 



A main storage address has not been 
provided. 



Result 

A return code of 4 is placed 

in register 15. 

A write-to-programmer is 
issued, the request for 
this DCB is ignored, and 
a return code of 4 is 
placed in register 15. 

Abnormal termination of task 
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LABEL 

The LABEL macro instruction can be used in three ways. 

1. To write standard and nonstandard volume label sets onto tape in 
EBCDIC or ASCII. 

2. To construct a parameter list. 

3. To refer to or modify a remote parameter list. 

WRITE VOLUME SETS (BSAM AND QSAM — TAPE ONLY) 

The LABEL macro instruction is written as follows: 

r t t 1 

| Name | Operation! Operand | 

j. _ + + j 

| [symbol] | LABEL | unit, ddname, labell, number, | 

| | j length, code (REWIND) | 

| | | ,\unload£ label2 j 

I X J. J 

unit 

indicates the relative number of the unit control block (UCB) for 
the volume that is mounted. 

ddname 

indicates the address of an eight-byte area containing the ddname 
that corresponds to the DDNAME parameter on the DD statement used 
to allocate the tape drives. The ddname is left- justified in this 
eight-byte area and padded to the right with blanks, if necessary. 

label 1 

indicates the address of the first volume that is to be written 
onto the tape that was mounted by the operator. One volume label 
is required for each label that is to be written, and the label (s) 
must be either in ASCII or in EBCDIC. An 80-byte area must be set 
up immediately following the last label to be written. The first 
four bytes of this area must contain , HDRl t (in either ASCII or 
EBCDIC) . For EBCDIC labels, the remaining 76 bytes must contain 
EBCDIC zeros. For ASCII labels, byte 11 (the accessability byte) 
must contain an ASCII blank and the remaining 75 bytes must contain 
ASCII zeros. 

number 

indicates the number of labels to be written. 

length 

indicates the length in bytes of the label (s) to be written. 

code 

specifies one of the following codes: 

9 7C2 7T1 

9D2 7E0 7T2 

9D3 7E1 7TE0 

7C0 7E2 7TE1 

7C1 7T0 7TE2 
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where : 

indicates 200 bits-per-inch (bpi) 

1 indicates 556 bpi 

2 indicates 800 bpi 

3 indicates 1600 bpi 

7 indicates 7- track tape 

9 indicates 9-track tape 

C indicates convertor on 

D indicates dual density 

E indicates even parity 

T indicates translator on 

REWIND 

indicates that the tape is to be rewound to load point after being 
labeled. If neither REWIND nor UNLOAD is specified, REWIND is 
assumed. 

UNLOAD 

indicates that the tape is to be unloaded and rewound after being 
labeled. 

label 2 

indicates the address of the first ten bytes of the volume labels. 
If EBCDIC labels are being written, this address may be the same as 
the address of the labell operand. (If this is the case, the 
label2 operand need not be coded.) If ASCII labels are being 
written, the label 2 operand indicates the address of an area 
containing the first ten bytes of the volume label converted to 
EBCDIC. 

Control is returned to the instruction following the LABEL macro 
instruction. When control is returned, register 15 contains one of 
the following return codes: 

Hexadecimal Code Meaning 

00 Labeling was successful. 

04 Operator has prevented labeling. 

08 The allocated tape drive cannot be accepted. 

0C Permanent input/output error. 

LIST FORM 

The list form of the LABEL macro instruction is used to construct a 
parameter list. Only the code and the MF=L operands must be coded; the 
other standard form operands are optional. 

EXECUTE FORM 

The execute form of the LABEL macro instruction refers to, and can 
modify, a remote parameter list created by the list form of the macro 
instruction. The MF=(E,listname) is the only required operand, where E 
indicates the execute form and listname points to the parameter list. 
If any other operands of the standard form are coded, their values 
replace the values in the parameter list. 
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Adding a Universal Character Set Image 
or a Forms Control Buffer Image 
to the Image Library 



This chapter provides a detailed 
description of how to add either an IBM UCS 
character set image or an IBM FCB forms 
control image to SYSl.IMAGELIB. 

Before reading this section, you should 
be familiar with the information contained 
in the publications listed below. 



REFERENCE PUBLICATIONS 

IBM 2821 Control Unit , GA24-3312, contains 
the information necessary to create a 
user-designed chain/train for the 1403 
printer unit. 

IBM System/360 Operating System: Data 
Management Macro Instructions , GC26-3794, 
describes the SETPRT macro instruction that 
loads a UCS image and an FCB image into 
their respective buffers. 

IBM System/360 Operating System: 
| Job Control Language Reference , GC28-6704, 
describes the UCS and FCB parameters that 
can be specified in a DD statement to load 
the UCS and FCB buffers when they are 
opened. 

IBM 3211 Printer and 3811 Control Unit 
Component Description . GA24-3453, contains 
the information necessary to create a 
user-designed train for the 3211 printer. 
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How to Add a UCS Image to the Image Library 

The IBM standard character set images listed in the following table may 
be included in SYSl. IMAGELIB at system generation by using the UCS macro 
instruction. The member name for an image in the image library is 
developed by prefixing a character set code shown in the table with UCSl 
or UCS2. UCSl denotes a 1403 printer image and UCS2 denotes a 3211 
printer image (for example, UCS1AN or UCS2A11). 



r 1 

| 1403 AN, HN, PCAN, PCHN, PN, QNC, QN, RN, SN, TN, XN, YN | 
^ _ J 

j 3211 All, Gil, Hll, Pll, Til J 

l J 



You may add a user-designed character image to the image library or 
make an existing image a default image by following these rules: 

1. The member name must be either the four characters UCSl for the 
1403 or UCS2 for the 3211 printer- The member name must be 
followed by a unique character set code that is one to four 
characters long. This character set code can be any valid 
combination of letters and numbers according to the rules for 
assembler language symbols. The single letters U or C should not 
be used as a character set code since they are symbols for special 
conditions recognized by the system. The assigned character set 
code must be specified on the DD statement or SETPRT macro 
instruction to load the image into the UCS buffer. 

2. The first byte in the load module of a character set image 
specifies whether or not the image is a default. A default image 
is indicated by X*80*, and is used when the UCS parameter is not 
coded in the DD statement. X'00* specifies that the image is not 
to be used as a default. 

3. The second byte of the load module indicates the number of lines 
(n) to be printed for image verification. 

4. Each byte if the next n bytes indicates the number of characters to 
be printed on each verification line. (Note: For the 3211 
printer, the maximum number of characters printed per line is 48; 
the associative bytes are not printed during verification.) 

5. A 240 byte 14 03 UCS image or a 512 byte 3211 UCS image must follow 
the previously described fields. (A 3211 UCS image has 432 
characters, followed by 16 bytes to be left blank, and 64 bytes if 
associative bits.) Two apostrophes or two ampersands must be coded 
to represent a single apostrophe or a single ampersand, 
respectively, which is a part of a character set image. 
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The following code is an example of adding a 1403 UCS image, YN f to 
the image library. 



//ADDYN JOB MSGLEVEL=1 

//STEP EXEC PROC=ASMFCL,PARM.ASM='NODECK,LOAD , f X 

// PARM. LKED= • LI ST , NCAL f NE , OL* 

//ASM.SYSIN DD * 



UCS1YN 



CSECT 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

END 



X'80' (this is a default image) 
ALK6) (number of lines to be printed) 
ALK39) (39 characters printed on 1st line) 
ALK42) (42 characters printed on 2nd line) 
ALK39) (39 characters printed on 3rd line) 
ALK39) (39 characters printed on 4th line) 
ALK42) (42 characters printed on 5th line) 
ALK39) (39 characters printed on 6th line) 
C • 1234567890STABCDEFGHIJKLMNOPQRSTUVWXYZ* , . " 
C , 1234567890STABCDEFGHIJKLMNOPQRSTUVWXYZ*, . #-$* 
C ■ 1234567890STABCDEFGHIJKLMNOPQRSTUVWXYZ* , . f 
C ■ 1234567890STABCDEFGHIJKLMNOPQRSTUVWXYZ* , . » 
C • 1234567890STABCDEFGHIJKLMNOPQRSTUVWXYZ*, . #-$■ 
C ■ 1234567890STABCDEFGHIJKLMNOPQRSTUVWXYZ* , . ■ 



/* 

//LKED. SYSLMOD DD DSNAME=SYS1 . IMAGELIB (UCS1YN) , DISP=OLD 
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The following example shows the code used to add a 3211 UCS image 
(All) to the image library. The first 432 bytes of the 3211 UCS image 
correspond to the 432 positions on the print train. The next 16 bytes 
are left blank, followed by 64 bytes of associative bits used to screen 
data checks. See the publication IBM 3211 Printer and 3811 Control Unit 
Component Description , GA24-3543, to determine how to code these bits 
for a particular train. 

r t 

//ADDA11 JOB MSGLEVEL=1 

//STEP EXEC PROC=ASMFCL , PARM. ASM= ■ NODECK , LOAD t , 

// PARM. LKED= » LI ST , NCAL , NE , OL * 

//ASM.SYSIN DD * 

USC2A11 CSECT 

DC X^BO 1 (THIS IS A DEFAULT IMAGE) 

DC ALIO) (NUMBER OF LINES TO BE PRINTED) 

DC ALK48) (48 CHARACTERS PRINTED ON 1ST LINE) 

DC ALK48) (48 CHARACTERS PRINTED ON 2ND LINE) 

DC ALK48) (48 CHARACTERS PRINTED ON 3RD LINE) 

DC ALK48) (48 CHARACTERS PRINTED ON 4TH LINE) 

DC ALK48) (48 CHARACTERS PRINTED ON 5TH LINE) 

DC ALK48) (48 CHARACTERS PRINTED ON 6TH LINE) 

DC ALK48) (48 CHARACTERS PRINTED ON 7TH LINE) 

DC ALK48) (48 CHARACTERS PRINTED ON 8TH LINE) 

DC ALK48) (48 CHARACTERS PRINTED ON 9TH LINE) 

DC C , 1234567890#a/STUWXYZ&S,%JKLNMOPQR-$*ABCDEFGHI=. 

DC C'1234567890#a/STUVWXYZ&&,%JKLNMOPQR-$*ABCDEFGHI=. 

DC C ■ 12345678 9 0#a/STUVWXYZ&& , %JKLNMOPQR-$*ABCDEFGHI=. 

DC C 1234567890#a/STUVWXYZSS , %JKLNMOPQR-$*ABCDEFGHI=. 

DC C'1234567890#a/STUVWXYZ&&,%JKLNMOPQR-$*ABCDEFGHI=. 

DC C , 1234567890#a/STUVWXYZ&g,%JKLNMOPQR-$*ABCDEFGHI=. 

DC C , 1234567890#a/STUVWXYZgS,%JKLNMOPQR-$*ABCDEFGHI=. 

DC C ■ 123456789 0# a/STUVWXY Z S & , %JKLNMOPQR- $ * ABCDEFGHI= . 

DC C , 1234567890#a/STUWXYZ&S,%JKLNMOPQR-$*ABCDEFGHI=. 

DC 16C f • 

DC X* 00000000000000000000000000000000001010101010101010* 

DC X , 10004040004000401010101010101010100040400000004040 , 

DC X , 10101Q10101010100040400000001010101010101010101000 , 

DC X" 4040000000* 

END 

/* 

//LKED. SYSLMOD DD DSNAME=SYSl. IMAGELIB (UCS2A11) , DlSP=OLD 



Note ; Executing the assembler procedure does not actually generate 
executable code. The assembler /linkage editor is used as a vehicle to 
load the UCS image into the image library. 
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How to Add a Forms Control Buffer Image to the Image Library 

Two standard FCB images, STD1 and STD2, can be included in SYSl. IMAGELIB 
during system generation for a 3211 printer. STD1 prints six lines per 
inch on a 8 1/2 inch form. STD2 prints six lines per inch on an eleven 
inch form. Channels for both images are evenly spaced with channel one 
on the fourth line and channel nine on the last line. 

In addition to the IBM- supplied images, user images can be defined. 
Each user image is added to the image library as part of a load module. 
To add an FCB image to the image library, follow these rules : 

1. The member name cannot exceed eight bytes. The first four 
characters of this member name must be FCB2. The characters that 
follow FCB2 identify the FCB image and are referred to as the image 
identifier. Any combination of characters that are valid in 
assembly language can be used with the exception of a single "S" or 
a single "U" as an image identifier. The image identifier must be 
specified on a DD statement or in the SETPRT macro instruction to 
load the image in the FCB buffer. 

2. The first byte of the load module of a forms control image 
specifies whether or not the image is a default. A default image 
is indicated by X*80* and is used for all jobs that do not have the 
FCB parameter coded on the DD statement; X'OO' indicates that the 
image is not to be used as a default. 

3. The second byte of the load module indicates the number of lines 
per form (FCB image length). The maximum image length is 180 
lines. The FCB image must be as long as the form. For example, if 
you are printing eight lines per inch on an eleven inch form, the 
FCB image must be 88 bytes long; if you are printing six lines per 
inch on the same form, the FCB image must be 66 bytes long. 

4. The first of the FCB image (the third byte of the load module) 
defines the number of lines per inch and a channel: 

• X'ln 1 means eight lines are printed per inch. 

• X'On* means six lines are printed per inch. 

All remaining bytes (lines) must contain X'On* except the last 
byte. The last byte must be X'ln*. The letter n can be a 
hexadecimal value from 1 to C representing a channel (one to 
twelve) ; or it can be zero (0) which means no channel is indicated. 

In the following example, an FCB load module is assembled and added 
to SYSl. IMAGELIB. The image defines a print density of eight lines per 
inch on an eleven inch form. 
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//ADDFCB JOB MSGLEVEL=1 

//STEP EXEC PROC=ASMFCB,PARM.ASM= , NODECK,LOAD , # X| 

// PARM. LKED= » LI ST , NCAL, NE , OL * 

//ASM. SYSIN DD * 

FCB2ID1 CSECT 

♦THIS EXAMPLE IS FOR A FORM LENGTH OF 11 INCHES 

♦WITH 8 LINES OF PRINT PER INCH (88 LINES) 

DC X^O* THIS IS A DEFAULT IMAGE 

DC ALK88) LENGTH OF FCB IMAGE 

DC X^O* 8 LINES PER INCH-NO CHANNEL FOR POS. 1 

DC XL 4*0* 4 LINES NO CHANNEL 

DC X'Ol' CHANNEL 1 IN POSITION 6 

DC XLe'O* 6 LINES NO CHANNEL 

DC X , 02" CHANNEL 2 IN POSITION 13 

DC XL6 » ' 

DC X'OS* 

DC XL6 • • 

DC X*0U - - 

DC XL6"0-' 

DC X'OS* 

DC XL6 ■ • 

DC x'oe* 

DC XL6 " * 

DC X'O?* 

DC XL6 * • 

DC X'OS* 

DC XL6 • ■ 

DC X , 09 l 

DC XL6 • ' 

DC X'OA 1 

DC XL6 ' ■ 

DC X'OB* 

DC XL6 ■ ' 

DC X'OC* CHANNEL 12 IN POSITION 83 

DC XLVO' 4 LINES NO CHANNEL 

DC X'10* POSITION 88 - LAST LINE IN IMAGE 

END 
/* 
//LKED. SYSLMOD DD DSNAME=SYSl . IMAGELIB (FCB2ID1) , DISP=OLD 
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Index 



Indexes to systems reference library 
manuals are consolidated in the publication 
IBM System/360 Operating System: Systems 
Reference Library Master Index , Order No. 
GC28-6644. For additional information 
about any subject listed below, refer to 
other publications listed for the same 
subject in the Master Index. 
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VTOC maintenance 



CAMLST macro instruction 
used in cataloging, 
16-29,129 
catalog (SYSCTLG) 

entries and blocks 31 
index 

how to build 19 
how to delete 20 
index name used to read a block from 
reading, maintaining 16 
CATALOG macro instruction 
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Iwhen index levels exist 
by creating index levels 
channel program 

use in EXCP 50 
CLOSE macro instruction 

in EXCP 70 
control volumes, how to 
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t CVT macro instruction 96 
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DDR 
| dynamic device reconfiguration 
use in EXCP 62 
DEB (Data Extent Block) 

in IECDSECT 40 

use in EXCP 51,73 
defective track recovery 

see: ATLAS 
device codes 

used by DEVTYPE macro instruction 113 

used in catalog volume list pointers 34 
DEVTYPE system macro instruction 111 
DOS initialized volume 

use in OS 29 
DSCB (Data Set Control Block) 

in IECDSECT 38 

reading from VTOC 26 



ECB (Event control block) 

in IECDSECT 39 

use in EXCP 51,72,73 

use in XDAP 91,92 
EOV macro instruction 

in EXCP 69 

in XDAP 91 
EXCP processing 

appendages 54 

channel program 50 

control blocks 50,70 

description 48 

EXCP macro instruction 69 

macro instructions 61 

RESTORE, PURGE macro instruction 74,75 

FCB (see Forms Control Buffer) 
file label 

in IECDSECT 37 
forms control buffer 
| image on SYS1. IMAGELIB 125 



generation data set 

used in reading a block from the cata- 
log 17 
generation index 

how to build 20 



data set 

delete from catalog 27 

delete from VTOC 24,25 

enter in catalog 23, 24 

label 

in IECDSECT 37 

protection 97-107 

recatalog 25 

rename in VTOC 28 
DCB (Data Control Block) 

in IECDSECT 40 

macro instruction, macro expansion 
EXCP 64-67 

use in EXCP 51,61 
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IECDSECT system macro instruction 36-40 
IECDSECS macro instruction 36 
IECPCNVT 

TTR address conversion routine 93 
IEFJFCBN macro instruction 44,45 
IEHPROGM utility program 

use in data set protection 99 
image library 122-126 
index level 

name used to read a block from the 
catalog 16 

used in cataloging a data set 23 

used in uncataloging a data set 24 
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INDEX macro instruction 

used in cataloging 19-23,129 
IOB (Input/Output Block) 

in IECDSECT 39, 40 

use in EXCP 50,70 

use in XDAP 88,9 2 
I/O interruption 

processing in EXCP 53 
I/O supervisor 

appendages 54-59 

processing in EXCP 51-53 

JFCB (Job File Control Block) 
in IECDSECT 39 
in IEFJFCBN 44,45 
reading, modifying before OPEN 115 



| LABEL macro instruction 119,120 
LOCATE macro instruction 

use in cataloging 17-19,129 



macro instructions 

described in this publication 110 
message 

in IECDSECT 39 
Model 19 5 

use of EXCP 48 



PURGE macro instruction 
use in EXCP 75 



RDJFCB macro instruction 116 
reading a JFCB 

use of system macro instructions 115 
relative track address 

see: TTR 
RENAME macro instruction 

use in VTOC maintenance 29,129 

use with password data set 101 
RESTORE macro instruction 

use in EXCP 74 



SCRATCH macro instruction 

use in VTOC maintenance 28,129 
use with password data set 101 



track errors 

see: ATLAS 
TTR (Relative track address) 

conversion to and from absolute address 

93 
used to read a block from the catalog 
18 
TYPE=J 

operand of OPEN 115,116 



OBTAIN macro instruction 

use with VTOC 26,129 
OPEN macro instruction 

after modifying a JFCB 115 

in EXCP 68 

in XDAP 89 



password data set (PASSWORD) 

key area, data area of password record 
99 

SCRATCH, RENAME 101 

use of 100 
protected data set 

see : Password data set 
PROTECT macro instruction 

maintaining the password data set 101 

number of records for each protected 
data set 102 

parameter lists 103 

programming conventions 103 

protection mode indicator 102 

return codes 107 



UCB (Unit Control Block) 

in DEVTYPE macro instruction 111 

in IEFUCBOB macro instruction 41 
UCS (Universal Character Set) 

image on SYSl. IMAGELIB 122 
USASCII 

in UCB macro definition 42 



volume label 

in IECDSECT 37 
VTOC (Volume Table of Contents) 

maintenance 26 



XDAP processing 

channel program 88 
control blocks 91,92 
description 88 
macro instructions 89 
TTR conversion 9 3 
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Macro Instructions Required to Maintain and Modify the Catalog and VTOC 



Function 


Macro -Instructions Required to Perform Function 


Name 


Operation 


Operands 


Read a block from the 
catalog -by name 


[symbol ] 
[ list-name] 


LOCATE 
CAMLST 


list-addrx 1 r "] 
NAME,dsname-relexp 6 , [cvol-relexp 7 J ,area-relexp 9 


Read a block from the 
catalog -by location 


[symbol ] 
[ list-name] 


LOCATE 
CAMLST 


list-addrx 1 r -i 
BLOCK,ttr-relexp 3 , [cvol-relexp 7 J ,area-relexp 9 


Build an index 


[ symbo 1 ] 
[ list-name ] 


INDEX 
CAMLST 


1 ist-addrx 1 r -i 
BLDX, name-re lexp , I cvol-relexp 


Build a generation 
index 


[ symbol ] 
[ list-name ] 


INDEX 
CAMLST 


list-addrx 1 r -i r -i r -i 

BLDG, name-relexp 2 , [cvol-relexp 7 J ,,[DELETE 15 J , [EMPTY 16 ] ,number-absexp 17 


Assign an alias 


[ symbo 1 ] 
[ list-name] 


INDEX 
CAMLST 


list-addrx 1 r -i 

BLDA, index name-relexp 5 , [cvol-relexp 7 J ,alias name-relexp 10 


Delete an index 


[ symbol ] 
[ list-name] 


INDEX 
CAMLST 


list-addrx 1 r -i 
DLTX, name-re lexp , [cvol-relexp J 


Delete an alias 


[symbol ] 
[ list-name] 


INDEX 
CAMLST 


list-addrx 1 r -i 
DLTA, alias name-relexp 10 , [cvol-relexp 7 J 


Connect control 
volumes 


[ symbol ] 
[ list-name ] 


INDEX 
CAMLST 


list-addrx 1 r -| 

LNKX, index name-relexp , [cvol-relexp J ,new cvol-relexp 


Disconnect control 
volumes 


[ symbol ] 
[ list-name ] 


INDEX 
CAMLST 


list-addrx 1 r -i 
DRPX, index name-relexp , [cvol-addrx J 


Catalog a data set 
when index exists 


[symbol] 
[ list-name ] 


CATALOG 
CAMLST 


list-addrx 1 r ~i r -i 
CAT, name-relexp 2 , [cvol-relexp 7 J ,vol list-relexp 13 , [DSCBTTR^dscb ttr-relexp 19 J 


Catalog a data set and 
create indexes 


[ symbo 1 ] 
[ list-name] 


CATALOG 
CAMLST 


list-addrx 1 r "| r -] 
CATBX, name-relexp 2 , [cvol-relexp 7 J ,vol list-relexp 13 ,[DSCBTTR=<dscb ttr-relexp 19 ] 


Remove data set 
references from the 
catalog and leave 
indexes 


[ symbo 1 ] 
[ list-name] 


CATALOG 
CAMLST 


list-addrx 1 r -, 
UNCAT, name-relexp , [cvol-relexp 


Remove data set 
references from the 
catalog along with 
empty indexes 


[ symbol ] 
[ list-name ] 


CATALOG 
CAMLST 


list-addrx 1 ■- -, 
UCATDX,name-relexp , cvol-relexp 


Recatalog a data set 


[ symbo 1 ] 
[ list-name] 


CATALOG 
CAMLST 


list-addrx 1 r -j r -i 
RECAT, name-re lexp 2 , [cvol-relexp 7 J ,vol list-relexp 13 , [DSCBTTR=dscb ttr-relexp 19 J 


Read a DSCB from the 
VTOC - by name 


[ symbol ] 
[ list-name] 


OBTAIN 
CAMLST 


list-addrx 1 

SEARCH, dsname-relexp ,vol-relexp 8 ,wk area-relexp 


Read a DSCB from the 
VTOC - by location 


[symbol ] 
[ list-name] 


OBTAIN 
CAMLST 


list-addrx 1 

SEEK,cchhr-relexp 4 ,vol-relexp 8 ,wk area-relexp 


Delete a data set 


[ symbol ] 
[ list-name] 


SCRATCH 
CAMLST 


list-addrx 1 r t 
SCR ATCH,dsname-re lexp 6 ,, vol list-relexp 13 ,, [OVRD 18 ] 


Change the data set 
name in a DSCB 


[symbol] 
[ list-name] 


RENAME 
CAMLST 


list-addrx 1 

RENAME ,dsname-relexp 6 ,new name-relexp 11 ,vol list-relexp 13 



1 list-addrx 

points to the parameter list (labeled 
list-name) set up by the CAMLST 
macro instruction. 

2 name-relexp 

specifies the main storage location of the 
fully qualified name of a data set or index 
level. The name cannot exceed 44 
characters. If the name is less than 44 
characters, it must be followed by a blank. 
The name must be defined by a C-type 
Define Constant (DC) instruction. 

3 ttr-relexp 

specifies the main storage location of a 
3-byte relative track address (TTR). This 
address indicates the position, relative to 
the beginning of the catalog data set, of 
the track containing the block (TT), and 
the block identification on that track (R). 

cchhr-relexp 

specifies the main storage location of the 
5-byte absolute track address (CCHHR) of 
a DSCB. 

index name-relexp 

specifies the main storage location of the 
name of a high level index. The area 
that contains the name must be eight bytes 
long. The name must be defined by a C-type 
Define Constant (DC) instruction. 

dsname-relexp 

specifes the main storage location of a fully 
qualified data set name. The area that 
contains the name must be 44 bytes long. 
The name must be defined by a C-type Define 
Constant (DC) instruction. 

cvol-relexp 

specifies the main storage location of a 
6-byte volume serial number for the volume 
to be processed. If this parameter is not 
specified, the system residence volume is 
processed . 

vol -re lexp 

specifies the main storage location of the 
6-byte serial number of the volume on which the 
required DSCB is stored. 

area-re lexp 

specifies the main storage location of a 265-byte 
work area that you must define. The work area 
must begin on a doubleword boundary. The first 
256 bytes of the work area will contain the block 
that is read from the catalog, the next three bytes 
will contain zeros, and the last six bytes will 
contain the serial number of the volume on which 
the block was found. If the data set resides on 
one volume, bytes 252-254 will contain the 
relative track address of the DSCB. 

alias name-relexp 

specifies the main storage location of the name 
that is to be used as an alias for a high level 
index. The area that contains the name must be 
eight bytes long. The name must be defined by a 
C-type Define Constant (DC) instruction. 



11 new name-relexp 

specifies the main storage location of a fully 
qualified data set name that is to be used to 
rename a data set. The area that contains the 
name must be 44 bytes long. The name must 
be defined by a C-type Define Constant (DC) 
instruction. 

12 new cvol-relexp 

specifies the main storage location of the 
4-byte device code and 6-byte volume serial 
number of the control volume that is to be 
connected to another control volume. 

vol list-relexp 

specifies the main storage location of an area 
that contains a volume list. The area must 
begin on a half-word boundary. 

wk area-relexp 

specifies the main storage location of a 148 
byte work area that you must define. The 
work area must begin on a doubleword 
boundary. 

If a data set name was specified, the first 96 
bytes contain the data portion of a format 1 
DSCB, and the next five bytes contain the 
absolute track address of the DSCB. 

If an absolute track address was specified, the 
first 140 bytes contain the key portion and 
data portion of the DSCB. 

15 DELETE 

specifies that all data sets dropped from a 
generation data group are to be deleted, 
i.e., the space allocated to the data sets is 
to be made available for reallocation. 

16 EMPTY 

specifies that references to all data sets in a 
generation data group cataloged in the 
generation index are to be removed from the 
index when the number of entries specified is 
exceeded. 

number-absexp 

specifies the number of data sets to be 
included in a generation data group. This 
number must be specified, and cannot exceed 
255. 

18 OVRD 

specifies that the expiration date in the DSCB 
should be ignored. 

19 DSCBTTR=dscb ttr-relexp 

specifies the main storage location of the 
3-byte relative track address (TTR) of the 
DSCB for a data set that resides on only one 
volume (relative to the beginning of the 
VTOC). 
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EXCEPTIONAL RETURN CONDITION CODES 



Control is always returned to the instruction that follows the LOCATE, INDEX, CATALOG, OBTAIN, SCRATCH, or RENAME macro instruction. If the function 
has been performed successfully, register 15 contains zeros. Otherwise, register 15 contains a condition code that indicates the reason for the failure. 
The condition codes for the macro instruction are as follows: 



LOCATE Macro Instruction 



Code Interpretation 

4 Either the required control volume was not mounted, there is a 

closed chain of control volume pointers, the specified volume is a 
2321, or the specified volume does not contain a catalog data set 
(SYSCTLG). The work area contains the volume serial number 
(in bytes 259-264) and the device code of the volume, if available 
(In bytes 252-255).* 

8 One of the names of the qualified name was not found or an 

unidentified entry was found. Register contains the number of the 
last valid name in the qualified name. For example, if the qualified 
name A.B.C.D were specified, but name C did not exist at the 
level specified, register would contain the binary number 2. 
The work area contains the serial number of the volume containing 
the index (in bytes 259-264).* 

12 Either an index, an alias, or a control volume pointer was found 

when the list of qualified names was exhausted.* 

16 A data set resides at some level of the index other than the lowest 

index level specified. The work area contains the serial number of 
the volume containing the index in which a data set was found 
(in bytes 259-264).* 

20 A syntax error exists in the name (for example, nine characters, a 

double delimiter, blank name field, or a qualified name when a 
simple name is needed). 

24 A permanent I/O error was found when processing the catalog.* 

28 Relative track address (TTR) supplied to LOCATE is out of the 

SYSCTLG data set extents.* 

32 Invalid work area pointer (for example, not a double-word 

boundary). 

* Register contains the number of index levels that were searched before the 
failure was encountered. The work area contains the last block that was 
searched. 



OBTAIN Macro Instruction 


Code 
4 


Interpretation 

The required volume was not mounted. 


8 


The DSCB was not found in the VTOC of the specified volume. 


12 


A permanent I/O error was found when processing the specified 
volume. 


16 


Invalid workarea pointer. 


20 


CCHH not within boundaries of VTOC extent (Seek mode). 



CATALOG Macro Instruction 



Code Interpretation 

4 Either the required control volume was not mounted, or the 

specified volume does not contain a catalog data set (SYSCTLG). 

8 The existing catalog structure is inconsistent with the operation 

performed. (Because the CATALOG macro instruction uses the 
search routine of the LOCATE macro instruction, register 1 contains 
the condition code that would be given by the LOCATE macro 
instruction. See the adjacent chart for the interpretation of that 
code. Register contains the number of the index levels referred 
to before the exception was noted.) 

12 Not used with the CATALOG macro instruction. 

16 The index structure necessary to catalog the data set does not exist. 

20 Space is not available on the specified control volume. 

24 An attempt was made to catalog an improperly named generation 

data set, or the generation index is full and the named data set is 
older than any currently in the index. 

28 A permanent I/O error was found when processing the catalog. 

72 The VTOC of a DOS volume could not be converted to OS format. 



INDEX Macro Instruction 



Code Interpretation 

4 Either the required control volume was not mounted, or the specified 

volume does not contain a catalog data set (SYSCTLG). 

8 The existing catalog structure is inconsistent with the operation 

performed. (Because the INDEX macro instruction uses the search 
routine of the LOCATE macro instruction, register 1 contains the 
condition code that would be given by the LOCATE macro 
instruction, and register contains the number of index levels 
referred to during the search.) 

12 An attempt was made to delete an index or generation index that 

has an alias or has indexes or data sets cataloged under it. The 
index is unchanged. 

16 The qualified name specified when building an index or generation 

index implies an index structure that does not exist; the high level 
index, specified when connecting control volumes, does not exist. 

20 Space is not available on the specified control volume. 

24 Not used with the INDEX macro instruction. 

28 A permanent I/O error was found when processing the catalog. 

72 The VTOC of a DOS volume could not be converted to OS format. 



RENAME Macro Instruction 



Code Interpretation 



No volumes containing any part of the data set were mounted, nor 
was a UCB address contained in register 0, 

An unusual condition was encountered on one or more volumes. 



After the RENAME macro instruction is executed, the last byte of each 
12-byte volume pointer in the volume list indicates the following conditions 
in binary code: 

Code Interpretation 

The DSCB for the data set has been renamed in the VTOC on the 
volume pointed to. 

1 The VTOC of this volume does not contain the DSCB to be renamed, 

2 The macro instruction failed when the correct password was not 
supplied in the two attempts allowed. 

3 A DSCB containing the new name already exists in the VTOC of 
this volume. 

4 A permanent I/O error was found when processing this volume. 

5 A device for mounting this volume was unavailable. 

6 The operator was unable to mount this volume. 



SCRATCH Macro Instruction 



Code Interpretation 
4 



No volumes containing any part of the data set were mounted, nor 
was a UCB address contained in register 0. 

An unusual condition was encountered on one or more volumes. 



After the SCRATCH macro instruction is executed, the last byte of each 
12-byte volume pointer in the volume list indicates the following conditions 
in binary code: 

Code Interpretation 

The DSCB for the data set has been deleted from the VTOC on the 
volume pointed to. 

1 The VTOC of this volume does not contain the DSCB to be deleted. 

2 The macro instruction failed when the correct password was not 
supplied in the two attempts allowed. 

3 The DSCB was not deleted because either the OVRD option was not 
specified or the retention cycle has not expired. 

4 A permanent I/O error was found when processing this volume. 

5 A device for mounting this volume was unavailable. 

6 The operator was unable to mount this volume. 



Figure CTLG2. Return Codes of Catalog and VTOC Macro Instructions 
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